forgeos 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/forge/cli/commands.ts

@@ -78,6 +78,20 @@ import {
   formatTelemetryJson,
   runTelemetryCommand,
 } from "./telemetry.ts";
+import {
+  formatDeltaExplainHuman,
+  formatDeltaExplainJson,
+  formatDeltaStatusHuman,
+  formatDeltaStatusJson,
+  formatDeltaSessionHuman,
+  formatDeltaSessionJson,
+  formatDeltaTimelineHuman,
+  formatDeltaTimelineJson,
+  runDeltaExplain,
+  runDeltaSessionCommand,
+  runDeltaStatus,
+  runDeltaTimeline,
+} from "../delta/index.ts";
 import {
   formatPolicyHuman,
   formatPolicyJson,
@@ -151,6 +165,7 @@ import {
   formatAgentJson,
   runAgentCommand,
 } from "../agent-adapters/index.ts";
+import { runMcpServe } from "../agent-memory/mcp.ts";
 import {
   formatReviewHuman,
   formatReviewJson,
@@ -848,6 +863,44 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       );
       return result.exitCode;
     }
+    case "delta": {
+      const result = await runDeltaStatus(command.workspaceRoot);
+      process.stdout.write(command.json ? formatDeltaStatusJson(result) : formatDeltaStatusHuman(result));
+      return result.exitCode;
+    }
+    case "session": {
+      const result = await runDeltaSessionCommand({
+        workspaceRoot: command.workspaceRoot,
+        subcommand: command.subcommand,
+        sessionId: command.sessionId,
+        sourceSessionId: command.sourceSessionId,
+        operationId: command.operationId,
+        title: command.title,
+        limit: command.limit,
+      });
+      process.stdout.write(command.json ? formatDeltaSessionJson(result) : formatDeltaSessionHuman(result));
+      return result.exitCode;
+    }
+    case "timeline": {
+      const result = await runDeltaTimeline({
+        workspaceRoot: command.workspaceRoot,
+        target: command.target,
+        kind: command.kindFilter,
+        session: command.sessionId,
+        limit: command.limit,
+        rebuild: command.rebuild,
+      });
+      process.stdout.write(command.json ? formatDeltaTimelineJson(result) : formatDeltaTimelineHuman(result));
+      return result.exitCode;
+    }
+    case "explain": {
+      const result = await runDeltaExplain({
+        workspaceRoot: command.workspaceRoot,
+        thing: command.thing,
+      });
+      process.stdout.write(command.json ? formatDeltaExplainJson(result) : formatDeltaExplainHuman(result));
+      return result.exitCode;
+    }
     case "agent": {
       const result = await runAgentCommand(command.options);
       if (command.options.json) {
@@ -857,6 +910,9 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return result.exitCode;
     }
+    case "mcp": {
+      return runMcpServe(command.workspaceRoot);
+    }
     case "review": {
       const result = runReviewCommand(command.options);
       if (command.options.json) {

package/src/forge/cli/dev.ts

@@ -19,6 +19,7 @@ import {
 } from "../dev/server.ts";
 import { startDevWatch } from "../dev/watch.ts";
 import type { DevServerHandle } from "../dev/types.ts";
+import { createAmbientDeltaRecorder } from "../delta/index.ts";
 
 export interface DevCommandOptions {
   workspaceRoot: string;
@@ -443,6 +444,8 @@ export async function runDevCommand(
     return { web: webHandle, exitCode: 0 };
   }
 
+  const deltaRecorder = await createAmbientDeltaRecorder(workspaceRoot, "forge-dev", "forge dev");
+
   let handle: DevServerHandle;
   try {
     handle = await startDevServer({
@@ -460,8 +463,10 @@ export async function runDevCommand(
       mode: options.mode,
       allowDevAuth: options.allowDevAuth,
       webUrl,
+      deltaRecorder,
     });
   } catch (error) {
+    await deltaRecorder.close("forge dev failed to start");
     const message =
       error instanceof Error ? error.message : "failed to start dev server";
     if (options.json) {
@@ -507,7 +512,10 @@ export async function runDevCommand(
   }
 
   if (options.watch) {
-    watchHandle = startDevWatch(workspaceRoot, async (changedCount) => {
+    watchHandle = startDevWatch(workspaceRoot, async (changedCount, changedPaths) => {
+      for (const changedPath of changedPaths) {
+        await deltaRecorder.recordFileChanged(changedPath);
+      }
       const result = await run({
         workspaceRoot,
         check: false,
@@ -543,13 +551,14 @@ export async function runDevCommand(
   }
 
   await new Promise<void>((resolve) => {
-    const shutdown = () => {
-      watchHandle?.stop();
-      outboxWorkerHandle?.stop();
-      webHandle?.stop();
-      handle.stop();
-      resolve();
-    };
+      const shutdown = () => {
+        watchHandle?.stop();
+        outboxWorkerHandle?.stop();
+        webHandle?.stop();
+        handle.stop();
+        void deltaRecorder.close("forge dev stopped");
+        resolve();
+      };
 
     process.once("SIGINT", shutdown);
     process.once("SIGTERM", shutdown);

package/src/forge/cli/main.ts

@@ -4,6 +4,7 @@ import { isMainModule } from "../platform/module.ts";
 import { executeCommand } from "./commands.ts";
 import { hasUnknownOption, parseCli } from "./parse.ts";
 import { formatJsonResult } from "./output.ts";
+import { recordParsedCliCommand } from "../delta/index.ts";
 
 function formatHelp(): string {
   return [
@@ -14,6 +15,8 @@ function formatHelp(): string {
     "  forge dev --once --json   One-shot health/diagnostic loop for agents and CI",
     "  forge do \"fix\" --json     Ask ForgeOS for the right workflow and commands",
     "  forge inspect all --json  Read the generated machine contract",
+    "  forge mcp serve          Serve ForgeOS Agent Memory tools over MCP stdio",
+    "  forge agent context --current --json  Read the Agent Memory context pack",
     "  forge doctor windows --json  Diagnose native Windows setup and Bun shims",
     "  forge bench compiler --json  Measure public compiler phase timings",
     "  forge manifest validate ./forge.manifest.json --json  Validate an external runtime manifest",
@@ -86,7 +89,15 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
     return 1;
   }
 
-  return executeCommand(parsed.command);
+  const startedAt = Date.now();
+  const exitCode = await executeCommand(parsed.command);
+  await recordParsedCliCommand({
+    command: parsed.command,
+    argv,
+    exitCode,
+    durationMs: Date.now() - startedAt,
+  });
+  return exitCode;
 }
 
 if (isMainModule(import.meta)) {

package/src/forge/cli/new.ts

@@ -45,6 +45,7 @@ const REQUIRED_GITIGNORE_PATHS = [
   "forge.lock",
   ".forge/cache/",
   ".forge/pglite/",
+  ".forge/delta/",
   ".forge/local/",
   ".forge/test-cache/",
   ".forge/test-runs/",

package/src/forge/cli/parse.ts

@@ -164,9 +164,24 @@ export type ForgeCommand =
   | { kind: "do"; options: ForgeDoOptions }
   | { kind: "bench"; options: BenchCommandOptions }
   | { kind: "agent"; options: AgentCommandOptions }
+  | { kind: "mcp"; subcommand: "serve"; workspaceRoot: string }
   | { kind: "review"; options: ReviewCommandOptions }
   | { kind: "ui"; options: UiCommandOptions }
   | { kind: "manifest"; subcommand: "validate" | "import"; path: string; json: boolean; workspaceRoot: string }
+  | { kind: "delta"; subcommand: "status"; json: boolean; workspaceRoot: string }
+  | { kind: "timeline"; target?: string; kindFilter?: string; sessionId?: string; limit?: number; json: boolean; rebuild: boolean; forAgent: boolean; workspaceRoot: string }
+  | { kind: "explain"; thing: string; json: boolean; workspaceRoot: string }
+  | {
+      kind: "session";
+      subcommand: "list" | "show" | "rename" | "merge" | "split" | "detach";
+      sessionId?: string;
+      sourceSessionId?: string;
+      operationId?: string;
+      title?: string;
+      limit?: number;
+      json: boolean;
+      workspaceRoot: string;
+    }
   | { kind: "generate"; check: boolean; dryRun: boolean; json: boolean; concurrency: number }
   | { kind: "add"; alias: string; options: AddOptions & { workspaceRoot: string } }
   | { kind: "inspect"; target: InspectTarget; json: boolean; dryRun: boolean }
@@ -322,6 +337,7 @@ export const TOP_LEVEL_COMMANDS = [
   "self-host",
   "agent-contract",
   "agent",
+  "mcp",
   "review",
   "ui",
   "doctor",
@@ -339,6 +355,10 @@ export const TOP_LEVEL_COMMANDS = [
   "repair",
   "do",
   "bench",
+  "delta",
+  "session",
+  "timeline",
+  "explain",
   "manifest",
   "generate",
   "add",
@@ -515,6 +535,10 @@ const AGENT_SUBCOMMANDS: AgentSubcommand[] = [
   "doctor",
   "print-context",
   "clean",
+  "install",
+  "ingest",
+  "context",
+  "memory",
 ];
 const REVIEW_SUBCOMMANDS: ReviewSubcommand[] = ["inspect", "list", "explain"];
 const REVIEW_MODES: ReviewMode[] = ["quick", "standard", "strict"];
@@ -872,12 +896,27 @@ export function parseCli(argv: string[]): ParsedCli {
     case "agent": {
       const subcommand = rest[0] as AgentSubcommand | undefined;
       if (!subcommand || !AGENT_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge agent requires subcommand: list-targets, export, check, doctor, print-context, or clean");
+        errors.push("forge agent requires subcommand: list-targets, export, check, doctor, print-context, clean, install, ingest, context, or memory");
         return { command: null, workspaceRoot, errors };
       }
+      const inputRaw = parseOptionValue(argv, "--input");
+      let input: unknown;
+      if (inputRaw !== undefined) {
+        try {
+          input = JSON.parse(inputRaw);
+        } catch {
+          errors.push("--input must be valid JSON");
+        }
+      }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
       const target =
         (parseOptionValue(argv, "--target") as AgentAdapterTarget | undefined) ??
-        (subcommand === "export" || subcommand === "clean" ? "generic" : "generic");
+        (subcommand === "install" || subcommand === "ingest" ? rest[1] : undefined) ??
+        "generic";
       return {
         command: {
           kind: "agent",
@@ -891,12 +930,33 @@ export function parseCli(argv: string[]): ParsedCli {
             preserveUserSections: !parseFlag(argv, "--no-preserve-user-sections"),
             skills: !parseFlag(argv, "--no-skills"),
             rules: !parseFlag(argv, "--no-rules"),
+            eventName: parseOptionValue(argv, "--event"),
+            input,
+            entry: parseOptionValue(argv, "--entry") ?? (subcommand === "context" && rest[1] !== "--current" ? rest[1] : undefined),
+            current: parseFlag(argv, "--current"),
+            limit: limit ? Math.floor(limit) : undefined,
           },
         },
         workspaceRoot,
         errors,
       };
     }
+    case "mcp": {
+      const subcommand = rest[0];
+      if (subcommand !== "serve") {
+        errors.push("forge mcp requires subcommand: serve");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "mcp",
+          subcommand,
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
     case "review": {
       const requested = rest[0] as ReviewSubcommand | undefined;
       const subcommand =
@@ -1540,6 +1600,94 @@ export function parseCli(argv: string[]): ParsedCli {
         errors,
       };
     }
+    case "delta": {
+      const subcommand = rest[0];
+      if (subcommand !== "status") {
+        errors.push("forge delta requires subcommand: status");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "delta",
+          subcommand,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "session": {
+      const subcommand = rest[0];
+      if (subcommand !== "list" && subcommand !== "show" && subcommand !== "rename" && subcommand !== "merge" && subcommand !== "split" && subcommand !== "detach") {
+        errors.push("forge session requires subcommand: list, show, rename, merge, split, or detach");
+        return { command: null, workspaceRoot, errors };
+      }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
+      const sessionId = rest[1];
+      return {
+        command: {
+          kind: "session",
+          subcommand,
+          sessionId: subcommand === "detach" ? undefined : sessionId,
+          sourceSessionId: subcommand === "merge" ? rest[2] : undefined,
+          operationId: subcommand === "split" ? rest[2] : subcommand === "detach" ? rest[1] : undefined,
+          title: subcommand === "rename" ? rest.slice(2).join(" ") : undefined,
+          limit: limit ? Math.floor(limit) : undefined,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "timeline": {
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const kindFilter = parseOptionValue(argv, "--kind");
+      const sessionId = parseOptionValue(argv, "--session");
+      const rebuild = rest[0] === "rebuild";
+      const target = rebuild ? undefined : rest.find((item) => item !== kindFilter && item !== limitRaw && item !== sessionId);
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
+      return {
+        command: {
+          kind: "timeline",
+          target,
+            kindFilter,
+            sessionId,
+            limit: limit ? Math.floor(limit) : undefined,
+            json: parseFlag(argv, "--json"),
+            rebuild,
+            forAgent: parseFlag(argv, "--for-agent"),
+            workspaceRoot,
+          },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "explain": {
+      const thing = rest[0] === "session" ? `session:${rest[1] ?? "current"}` : rest[0];
+      if (!thing) {
+        errors.push("forge explain requires a target");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "explain",
+          thing,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
     case "manifest": {
       const subcommand = rest[0];
       const path = rest[1];
@@ -2144,6 +2292,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--version",
     "--check",
     "--json",
+    "--for-agent",
     "--dry-run",
     "--plan",
     "--staged",
@@ -2197,6 +2346,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--policy",
     "--emit",
     "--event",
+    "--entry",
+    "--current",
     "--trigger",
     "--component",
     "--framework",
@@ -2264,6 +2415,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--no-worker",
     "--once",
     "--limit",
+    "--kind",
+    "--session",
     "--input",
     "--args",
     "--step",
@@ -2310,6 +2463,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--run-tests",
     "--model-level",
     "--live",
+    "--no-delta",
   ]);
 
   for (let index = 0; index < argv.length; index++) {
@@ -2332,6 +2486,7 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--policy" ||
         arg === "--emit" ||
         arg === "--event" ||
+        arg === "--entry" ||
         arg === "--trigger" ||
         arg === "--component" ||
         arg === "--package" ||
@@ -2375,6 +2530,8 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--db" ||
         arg === "--database-url" ||
         arg === "--limit" ||
+        arg === "--kind" ||
+        arg === "--session" ||
         arg === "--input" ||
         arg === "--args" ||
         arg === "--step" ||

package/src/forge/delta/classifier.ts

@@ -0,0 +1,52 @@
+import { extname } from "node:path";
+import { normalizePath } from "../compiler/primitives/paths.ts";
+
+export interface DeltaSemanticHint {
+  kind: string;
+  confidence: "high" | "medium" | "low";
+}
+
+export function classifyDeltaPath(path: string): DeltaSemanticHint[] {
+  const normalized = normalizePath(path);
+  const hints: DeltaSemanticHint[] = [];
+
+  if (normalized.startsWith("src/forge/_generated/")) {
+    hints.push({ kind: "artifact.generated", confidence: "high" });
+  } else if (normalized === "src/policies.ts" || normalized.includes("/policies/")) {
+    hints.push({ kind: "policy.change", confidence: "high" });
+  } else if (normalized.startsWith("src/commands/")) {
+    hints.push({ kind: "command.change", confidence: "high" });
+  } else if (normalized.startsWith("src/queries/")) {
+    hints.push({ kind: "query.change", confidence: "high" });
+  } else if (normalized.startsWith("src/actions/")) {
+    hints.push({ kind: "action.change", confidence: "high" });
+  } else if (normalized.startsWith("src/workflows/")) {
+    hints.push({ kind: "workflow.change", confidence: "high" });
+  } else if (normalized === "src/forge/schema.ts") {
+    hints.push({ kind: "schema.change", confidence: "high" });
+  } else if (normalized.endsWith(".manifest.json") || normalized === "forge.manifest.json") {
+    hints.push({ kind: "manifest.change", confidence: "high" });
+  } else if (normalized === "package.json" || normalized.endsWith("/package.json")) {
+    hints.push({ kind: "dependency.change", confidence: "medium" });
+  }
+
+  if (hints.length === 0) {
+    hints.push({ kind: `file.${extname(normalized).slice(1) || "unknown"}`, confidence: "low" });
+  }
+  return hints;
+}
+
+export function classifyArtifactKind(path: string): string {
+  const normalized = normalizePath(path);
+  if (normalized.startsWith("src/forge/_generated/")) {
+    return "generated-contract";
+  }
+  if (normalized.includes("security") || normalized.includes("proof")) {
+    return "evidence";
+  }
+  if (normalized.startsWith(".forge/")) {
+    return "local-state";
+  }
+  return "source";
+}
+

package/src/forge/delta/explain.ts

@@ -0,0 +1,126 @@
+import { DeltaStore } from "./store.ts";
+
+export interface DeltaExplainResult {
+  ok: true;
+  thing: string;
+  explanation: Record<string, unknown>;
+  exitCode: 0;
+}
+
+export async function runDeltaExplain(input: {
+  workspaceRoot: string;
+  thing: string;
+}): Promise<DeltaExplainResult> {
+  const store = await DeltaStore.open(input.workspaceRoot);
+  try {
+    return {
+      ok: true,
+      thing: input.thing,
+      explanation: await store.explain(input.thing),
+      exitCode: 0,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
+  const explanation = result.explanation;
+  if (explanation.type === "work-session") {
+    const session = explanation.session as Record<string, unknown> | null | undefined;
+    const lines = [result.thing, ""];
+    if (!session) {
+      lines.push("work session not found");
+      return `${lines.join("\n")}\n`;
+    }
+    lines.push("Work session:");
+    lines.push(`  ${String(session.id)}`);
+    lines.push(`  title: ${String(session.title ?? "Work session")}`);
+    lines.push(`  status: ${String(session.status ?? "unknown")}`);
+    lines.push(`  confidence: ${Number(session.confidence ?? 0).toFixed(2)}`);
+    if (session.summary) {
+      lines.push(`  summary: ${String(session.summary)}`);
+    }
+    const operations = Array.isArray(session.operations) ? session.operations as Array<Record<string, unknown>> : [];
+    lines.push("");
+    lines.push("Operations:");
+    for (const operation of operations.slice(-12)) {
+      const timestamp = typeof operation.timestamp === "string" ? operation.timestamp.slice(11, 16) : "??:??";
+      lines.push(`  ${timestamp} ${String(operation.kind)}${operation.summary ? ` ${String(operation.summary)}` : ""}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+  const runtime = explanation.runtime as Record<string, unknown> | null | undefined;
+  const semanticTimeline = explanation.semanticTimeline as Record<string, unknown> | null | undefined;
+  const semanticEvents = semanticTimeline && Array.isArray(semanticTimeline.events)
+    ? semanticTimeline.events as Array<Record<string, unknown>>
+    : [];
+  const currentState = semanticTimeline && semanticTimeline.currentState && typeof semanticTimeline.currentState === "object"
+    ? semanticTimeline.currentState as Record<string, unknown>
+    : {};
+  const proofs = Array.isArray(explanation.proofs) ? explanation.proofs as Array<Record<string, unknown>> : [];
+  const workSessions = Array.isArray(explanation.workSessions) ? explanation.workSessions as Array<Record<string, unknown>> : [];
+  const lines = [result.thing, ""];
+  lines.push("Type:");
+  lines.push(`  ${String(explanation.type ?? "unknown")}`);
+  lines.push("");
+  if (runtime) {
+    lines.push("Runtime:");
+    lines.push(`  kind: ${String(runtime.entry_kind ?? "unknown")}`);
+    lines.push(`  result: ${String(runtime.result ?? "unknown")}`);
+    if (runtime.diagnostic_code) {
+      lines.push(`  diagnostic: ${String(runtime.diagnostic_code)}`);
+    }
+    if (runtime.trace_id) {
+      lines.push(`  trace: ${String(runtime.trace_id)}`);
+    }
+    lines.push("");
+  }
+  lines.push("Semantic timeline:");
+  if (semanticEvents.length === 0) {
+    lines.push("  no matching operations");
+  } else {
+    for (const item of semanticEvents.slice(-12)) {
+      const timestamp = typeof item.timestamp === "string" ? item.timestamp.slice(11, 16) : "??:??";
+      lines.push(`  ${timestamp} ${String(item.kind)} ${String(item.title ?? item.summary ?? "")}`.trimEnd());
+    }
+  }
+  if (Object.keys(currentState).length > 0) {
+    lines.push("");
+    lines.push("Current state:");
+    for (const [key, value] of Object.entries(currentState)) {
+      if (value !== undefined) {
+        lines.push(`  ${key}: ${Array.isArray(value) ? value.join(", ") : String(value)}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Introduced in:");
+  if (workSessions.length === 0) {
+    lines.push("  no inferred work session linked");
+  } else {
+    const session = workSessions[0]!;
+    lines.push(`  ${String(session.id)} - ${String(session.title ?? "Work session")}`);
+    lines.push(`  confidence: ${Number(session.confidence ?? 0).toFixed(2)}`);
+    if (session.summary) {
+      lines.push(`  ${String(session.summary)}`);
+    }
+  }
+  lines.push("");
+  lines.push("Proofs:");
+  if (proofs.length === 0) {
+    lines.push("  none recorded");
+  } else {
+    for (const proof of proofs.slice(-6)) {
+      lines.push(`  ${String(proof.proof_kind)} -> ${String(proof.result)}`);
+    }
+  }
+  lines.push("");
+  lines.push("Git:");
+  lines.push(explanation.git ? "  linked metadata recorded" : "  no linked commit yet");
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatDeltaExplainJson(result: DeltaExplainResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/forge/delta/git-observer.ts

@@ -0,0 +1,43 @@
+import { execFileSync } from "node:child_process";
+
+function git(workspaceRoot: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, {
+      cwd: workspaceRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface DeltaGitSnapshot {
+  branch?: string;
+  head?: string;
+  dirty?: boolean;
+  changedPaths?: string[];
+  changedPathCount?: number;
+  changedPathsTruncated?: boolean;
+}
+
+export function readDeltaGitSnapshot(workspaceRoot: string): DeltaGitSnapshot {
+  const branch = git(workspaceRoot, ["branch", "--show-current"]) ?? undefined;
+  const head = git(workspaceRoot, ["rev-parse", "--short=12", "HEAD"]) ?? undefined;
+  const status = git(workspaceRoot, ["status", "--porcelain"]);
+  const allChangedPaths = status
+    ? status
+        .split(/\r?\n/)
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean)
+    : [];
+  const changedPaths = allChangedPaths.slice(0, 50);
+  return {
+    branch,
+    head,
+    dirty: allChangedPaths.length > 0,
+    changedPaths,
+    changedPathCount: allChangedPaths.length,
+    changedPathsTruncated: allChangedPaths.length > changedPaths.length,
+  };
+}