forgeos 0.1.0-alpha.30 → 0.1.0-alpha.32

package/src/forge/cli/changed.ts

@@ -4,6 +4,7 @@ import {
   filterCategorizedSummary,
   summarizeChangeTypes,
 } from "../workspace/change-summary.ts";
+import { forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
 import { buildWorkspaceGitSummary, type WorkspaceGitSummary } from "../workspace/git-summary.ts";
 
 export interface ChangedCommandResult {
@@ -44,6 +45,7 @@ interface GeneratedChangeExplanation {
 }
 
 const AUTHORED_CHANGE_TYPES = ["source", "tests", "docs", "config", "assets", "other"] as const;
+const REVIEW_CHANGE_TYPES = ["source", "tests", "docs", "config", "assets"] as const;
 
 function emptyCategory(summary: CategorizedFileSummary, category: keyof CategorizedFileSummary["byType"]): boolean {
   return summary.byType[category].count === 0;
@@ -87,10 +89,12 @@ function selectDerivedChangeSummary(summary: CategorizedFileSummary): DerivedCha
 function buildRisks(git: WorkspaceGitSummary): string[] {
   const risks: string[] = [];
   const changed = git.changeSummary.changed;
-  if (!git.available) {
+  if (!git.available && git.source === "forge-baseline") {
+    risks.push("git status is unavailable; using Forge workspace baseline for non-git change tracking");
+  } else if (!git.available) {
     risks.push("git status is unavailable; using filesystem inventory as untracked-file analysis");
   }
-  if (git.untracked.count > 0) {
+  if (git.untracked.count > 0 && git.source !== "forge-baseline") {
     risks.push(`${git.untracked.count} untracked file(s) are not in git history`);
   }
   if (changed.byType.other.count > 0) {
@@ -100,15 +104,24 @@ function buildRisks(git: WorkspaceGitSummary): string[] {
   if (!emptyCategory(changed, "generated") && humanChanges.total === 0) {
     risks.push("only generated artifacts changed; verify the source edit, generator input, or intentional regeneration that produced them");
   }
+  return risks;
+}
+
+function buildAdvisories(git: WorkspaceGitSummary): string[] {
+  const advisories: string[] = [];
+  const changed = git.changeSummary.changed;
   if (changed.total.count > 50) {
-    risks.push(`${changed.total.count} changed file(s) detected; use the grouped summaries before reviewing raw diffs`);
+    advisories.push(`${changed.total.count} changed file(s) detected; use grouped summaries before reviewing raw diffs`);
   }
-  return risks;
+  return advisories;
 }
 
 function buildRecommendedCommands(git: WorkspaceGitSummary): string[] {
+  if (!git.available && git.source === "forge-baseline") {
+    return ["forge handoff --json", "forge test plan --changed --json", "forge verify --changed", "git init"];
+  }
   if (!git.available) {
-    return ["forge status --json", "forge handoff --json", "git init"];
+    return ["forge baseline create --reason initial-scaffold --json", "forge status --json", "forge handoff --json", "git init"];
   }
   if (git.changeSummary.changed.total.count === 0) {
     return ["forge status --json", "forge dev --once --json"];
@@ -122,7 +135,12 @@ function buildRecommendedCommands(git: WorkspaceGitSummary): string[] {
       "forge generate --check --json",
     ];
   }
+  const authoredGeneratedInputs =
+    changed.byType.source.count +
+    changed.byType.config.count +
+    changed.byType.operational.count;
   return [
+    ...(authoredGeneratedInputs > 0 ? ["forge generate --check --json"] : []),
     "forge handoff --json",
     "forge test plan --changed --json",
     "forge verify --changed",
@@ -184,7 +202,7 @@ function buildGeneratedChangeExplanation(
   };
 }
 
-export function runChangedCommand(workspaceRoot: string, options: { authoredOnly?: boolean } = {}): ChangedCommandResult {
+export function runChangedCommand(workspaceRoot: string, options: { authoredOnly?: boolean; reviewOnly?: boolean } = {}): ChangedCommandResult {
   const git = buildWorkspaceGitSummary(workspaceRoot);
   const changed = git.changeSummary.changed;
   const humanChanges = selectHumanChangeSummary(changed);
@@ -193,20 +211,29 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
   const authoredStaged = filterCategorizedSummary(git.changeSummary.staged, [...AUTHORED_CHANGE_TYPES]);
   const authoredUnstaged = filterCategorizedSummary(git.changeSummary.unstaged, [...AUTHORED_CHANGE_TYPES]);
   const authoredUntracked = filterCategorizedSummary(git.changeSummary.untracked, [...AUTHORED_CHANGE_TYPES]);
-  const viewHumanChanges = options.authoredOnly ? selectHumanChangeSummary(authoredChanged) : humanChanges;
-  const viewChanged = options.authoredOnly ? authoredChanged : changed;
-  const viewStaged = options.authoredOnly ? authoredStaged : git.changeSummary.staged;
-  const viewUnstaged = options.authoredOnly ? authoredUnstaged : git.changeSummary.unstaged;
-  const viewUntracked = options.authoredOnly ? authoredUntracked : git.changeSummary.untracked;
-  const viewDerivedChanges: DerivedChangeSummary = options.authoredOnly
+  const reviewChanged = filterCategorizedSummary(changed, [...REVIEW_CHANGE_TYPES]);
+  const reviewStaged = filterCategorizedSummary(git.changeSummary.staged, [...REVIEW_CHANGE_TYPES]);
+  const reviewUnstaged = filterCategorizedSummary(git.changeSummary.unstaged, [...REVIEW_CHANGE_TYPES]);
+  const reviewUntracked = filterCategorizedSummary(git.changeSummary.untracked, [...REVIEW_CHANGE_TYPES]);
+  const viewHumanChanges = options.reviewOnly
+    ? selectHumanChangeSummary(reviewChanged)
+    : options.authoredOnly
+      ? selectHumanChangeSummary(authoredChanged)
+      : humanChanges;
+  const viewChanged = options.reviewOnly ? reviewChanged : options.authoredOnly ? authoredChanged : changed;
+  const viewStaged = options.reviewOnly ? reviewStaged : options.authoredOnly ? authoredStaged : git.changeSummary.staged;
+  const viewUnstaged = options.reviewOnly ? reviewUnstaged : options.authoredOnly ? authoredUnstaged : git.changeSummary.unstaged;
+  const viewUntracked = options.reviewOnly ? reviewUntracked : options.authoredOnly ? authoredUntracked : git.changeSummary.untracked;
+  const viewDerivedChanges: DerivedChangeSummary = options.authoredOnly || options.reviewOnly
     ? { total: 0, generated: { count: 0, sample: [], hidden: 0 } }
     : derivedChanges;
   const risks = buildRisks(git);
-  const recommendedCommands = buildRecommendedCommands(git);
+  const advisories = buildAdvisories(git);
+  const recommendedCommands = forgeCliCommandsForWorkspace(workspaceRoot, buildRecommendedCommands(git));
   const reviewFocus = buildReviewFocus(viewHumanChanges, viewDerivedChanges);
   const generatedExplanation = buildGeneratedChangeExplanation(viewHumanChanges, viewDerivedChanges);
   const diffPlan: DiffPlan = buildDiffPlanFromChangeSummary(viewChanged);
-  const ok = git.available || git.source === "filesystem";
+  const ok = git.available || git.source === "filesystem" || git.source === "forge-baseline";
 
   return {
     ok,
@@ -216,7 +243,9 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
       summary: {
         branch: git.branch,
         commit: git.commit,
-        view: options.authoredOnly ? "authored" : "all",
+        workspaceMode: git.workspaceMode ?? (git.available ? "git" : "nonGit"),
+        tracking: git.tracking ?? git.source,
+        view: options.reviewOnly ? "review" : options.authoredOnly ? "authored" : "all",
         changedFiles: viewChanged.total.count,
         humanFiles: viewHumanChanges.total,
         generatedFiles: viewDerivedChanges.total,
@@ -229,6 +258,9 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
       git: {
         available: git.available,
         source: git.source,
+        workspaceMode: git.workspaceMode,
+        tracking: git.tracking,
+        baseline: git.baseline,
         ...(git.error ? { error: git.error } : {}),
         branch: git.branch,
         commit: git.commit,
@@ -243,6 +275,7 @@ export function runChangedCommand(workspaceRoot: string, options: { authoredOnly
       generatedExplanation,
       diffPlan,
       risks,
+      advisories,
       recommendedCommands,
       nextActions: recommendedCommands,
     },
@@ -258,6 +291,7 @@ export function formatChangedHuman(result: ChangedCommandResult): string {
   const generatedExplanation = result.data.generatedExplanation as { summary?: string } | undefined;
   const diffPlan = result.data.diffPlan as { summary?: string; authoredDiffCommand?: string; generatedDiffCommand?: string; generatedCollapsedByDefault?: boolean } | undefined;
   const risks = (result.data.risks as string[] | undefined) ?? [];
+  const advisories = (result.data.advisories as string[] | undefined) ?? [];
   const nextActions = (result.data.nextActions as string[] | undefined) ?? [];
   const lines = [
     `Forge changed: ${result.ok ? "ready" : "git unavailable"}`,
@@ -300,6 +334,9 @@ export function formatChangedHuman(result: ChangedCommandResult): string {
   if (risks.length > 0) {
     lines.push("", "Risks:", ...risks.map((risk) => `  ${risk}`));
   }
+  if (advisories.length > 0) {
+    lines.push("", "Notes:", ...advisories.map((advisory) => `  ${advisory}`));
+  }
 
   lines.push("", "Next:", ...nextActions.map((command) => `  ${command}`));
   return `${lines.join("\n")}\n`;

package/src/forge/cli/commands.ts

@@ -181,6 +181,9 @@ import {
 import {
   formatDoctorHuman,
   formatDoctorJson,
+  formatPgliteDoctorHuman,
+  formatPgliteDoctorJson,
+  runPgliteDoctorCommand,
   runDoctorCommand,
 } from "./doctor.ts";
 import {
@@ -202,6 +205,16 @@ import {
   formatWorkOSJson,
   runWorkOSCommand,
 } from "./workos.ts";
+import {
+  formatLastHuman,
+  formatLastJson,
+  runLastCommand,
+} from "./last-run.ts";
+import {
+  formatBaselineHuman,
+  formatBaselineJson,
+  runBaselineCommand,
+} from "./baseline.ts";
 import { formatRlsHuman, formatRlsJson, runRlsCommand } from "./rls.ts";
 import {
   formatSecurityHuman,
@@ -271,7 +284,9 @@ import { resolveAuthFromCli } from "../runtime/auth/resolve.ts";
 import { getActiveDbAdapter } from "../runtime/executor.ts";
 import { CLI_VERSION, FORGEOS_VERSION } from "../version.ts";
 import type { CategorizedFileSummary } from "../workspace/change-summary.ts";
+import { forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
 import { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
+import { startCommandHeartbeat } from "./progress.ts";
 
 function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
   const absolute = join(workspaceRoot, relative);
@@ -708,33 +723,69 @@ export function runStatusCommand(workspaceRoot: string): StatusCommandResult {
   const driftClean = driftSummary.ok === true;
   const ok = driftClean && generatedReady;
   const handoffDefaultReady = handoffSummary.defaultReady === true;
+  const changed = gitSummary.changeSummary.changed;
+  const generatedGitFiles = changed.byType.generated.count;
+  const authoredGitFiles = changed.total.count - generatedGitFiles;
+  const authoredGeneratedInputs =
+    changed.byType.source.count +
+    changed.byType.config.count +
+    changed.byType.operational.count;
+  const generatedNeedsCheck = generatedReady && driftClean && generatedGitFiles === 0 && authoredGeneratedInputs > 0;
   const generatedState = !generatedReady
     ? "missing-artifacts"
+    : generatedNeedsCheck
+      ? "check-needed"
     : driftClean
       ? "ready"
       : "drift";
-  const generatedNextActions = generatedState === "ready"
-    ? ["forge dev", "forge generate --check --json"]
+  const generatedNextActionsRaw = generatedState === "ready"
+    ? ["forge dev", "forge dev --once --json", "forge generate --check --json"]
+    : generatedState === "check-needed"
+      ? ["forge generate --check --json", "forge handoff --json", "forge dev --once --json"]
     : ["forge generate", "forge check --json", "forge inspect drift --json"];
-  const changed = gitSummary.changeSummary.changed;
-  const generatedGitFiles = changed.byType.generated.count;
-  const authoredGitFiles = changed.total.count - generatedGitFiles;
+  const generatedNextActions = forgeCliCommandsForWorkspace(workspaceRoot, generatedNextActionsRaw);
   const generatedGitExplanation = generatedGitFiles === 0
-    ? "git status has no generated artifact changes"
+    ? generatedNeedsCheck
+      ? "git status has no generated artifact changes, but authored source/config changes mean freshness is unverified until forge generate --check runs"
+      : "git status has no generated artifact changes"
     : authoredGitFiles === 0
       ? "forge generate --check can be clean while git shows generated artifacts changed: generated files match current workspace inputs but differ from HEAD"
       : "git status includes generated artifacts alongside authored changes; review authored inputs first";
+  const [safeDevCommand, generatedCheckCommand, generatedRepairCommand] = forgeCliCommandsForWorkspace(workspaceRoot, [
+    "forge dev",
+    "forge generate --check --json",
+    "forge generate",
+  ]);
   const frontendPresent = summaryBlock.frontendPresent === true;
+  const [
+    studioOpenCommand,
+    studioAttachCommand,
+    studioSnapshotCommand,
+    studioWatchCommand,
+    studioBridgeCommand,
+    studioDoctorCommand,
+    studioStartTargetAppCommand,
+    studioProbeCommand,
+  ] = forgeCliCommandsForWorkspace(workspaceRoot, [
+    "forge studio open . --preview-port 5174 --target codex --json",
+    "forge studio attach . --preview-port 5174 --target codex --json",
+    "forge studio snapshot . --preview-port 5174 --target codex --json",
+    "forge studio watch . --preview-port 5174 --target codex --json",
+    "forge studio bridge . --preview-port 5174 --target codex --studio-url http://127.0.0.1:3765 --json",
+    "forge studio doctor . --preview-port 5174 --target codex --json",
+    "forge dev --port 3766 --web-port 5174",
+    "forge dev --once --json",
+  ]);
   const studio = {
-    openCommand: "forge studio open . --preview-port 5174 --target codex --json",
-    attachCommand: "forge studio attach . --preview-port 5174 --target codex --json",
-    snapshotCommand: "forge studio snapshot . --preview-port 5174 --target codex --json",
-    watchCommand: "forge studio watch . --preview-port 5174 --target codex --json",
-    bridgeCommand: "forge studio bridge . --preview-port 5174 --target codex --studio-url http://127.0.0.1:3765 --json",
-    doctorCommand: "forge studio doctor . --preview-port 5174 --target codex --json",
+    openCommand: studioOpenCommand,
+    attachCommand: studioAttachCommand,
+    snapshotCommand: studioSnapshotCommand,
+    watchCommand: studioWatchCommand,
+    bridgeCommand: studioBridgeCommand,
+    doctorCommand: studioDoctorCommand,
     targetPreviewUrl: "http://127.0.0.1:5174",
-    startTargetAppCommand: "forge dev --port 3766 --web-port 5174",
-    probeCommand: "forge dev --once --json",
+    startTargetAppCommand: studioStartTargetAppCommand,
+    probeCommand: studioProbeCommand,
     useful: frontendPresent,
     note: frontendPresent
       ? "Attach this app to Forge Studio as an external-agent workroom; Studio should preview the target app on 5174."
@@ -750,11 +801,13 @@ export function runStatusCommand(workspaceRoot: string): StatusCommandResult {
         state: generatedState,
         ready: generatedReady,
         driftClean,
+        freshness: generatedNeedsCheck ? "unverified" : generatedState === "ready" ? "verified-or-unchanged" : "attention",
+        authoredGeneratedInputs,
         missingArtifacts,
         tableDrift,
-        safeDevCommand: "forge dev",
-        checkCommand: "forge generate --check --json",
-        repairCommand: "forge generate",
+        safeDevCommand,
+        checkCommand: generatedCheckCommand,
+        repairCommand: generatedRepairCommand,
         git: {
           changedFiles: changed.total.count,
           authoredFiles: authoredGitFiles,
@@ -795,8 +848,11 @@ export function runStatusCommand(workspaceRoot: string): StatusCommandResult {
         },
       },
       git,
-      nextActions: ok
-        ? [
+      nextActions: forgeCliCommandsForWorkspace(
+        workspaceRoot,
+        ok
+          ? [
+            ...(generatedState === "check-needed" ? ["forge generate --check --json"] : []),
             "forge handoff --json",
             "forge changed --json",
             "forge dev",
@@ -805,7 +861,7 @@ export function runStatusCommand(workspaceRoot: string): StatusCommandResult {
             "forge inspect handoff --json",
             "forge verify --changed",
           ]
-        : [
+          : [
             "forge generate",
             "forge handoff --json",
             "forge changed --json",
@@ -813,6 +869,7 @@ export function runStatusCommand(workspaceRoot: string): StatusCommandResult {
             "forge inspect drift --json",
             "forge agent prepare --target codex --json",
           ],
+      ),
     },
     exitCode: ok ? 0 : 1,
   };
@@ -1558,6 +1615,16 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return 0;
     }
+    case "last": {
+      const result = runLastCommand({ workspaceRoot: command.workspaceRoot });
+      process.stdout.write(command.json ? formatLastJson(result) : formatLastHuman(result));
+      return result.exitCode;
+    }
+    case "baseline": {
+      const result = runBaselineCommand(command);
+      process.stdout.write(command.json ? formatBaselineJson(result) : formatBaselineHuman(result));
+      return result.exitCode;
+    }
     case "new": {
       const result = await runNewCommand({
         name: command.name,
@@ -1565,6 +1632,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         packageManager: command.packageManager,
         install: command.install,
         git: command.git,
+        fieldTest: command.fieldTest,
         forgePackageSpec: command.forgePackageSpec,
         localForge: command.localForge,
         workspaceRoot: command.workspaceRoot,
@@ -1627,7 +1695,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         concurrency: 4,
       });
       if (command.json) {
-        process.stdout.write(formatJsonResult(buildGenerateJson(result)));
+        process.stdout.write(formatJsonResult(buildGenerateJson(result, { workspaceRoot: command.workspaceRoot })));
       } else {
         process.stdout.write(formatAgentContractHuman(command.subcommand, result));
         writeHumanGenerate(result);
@@ -1668,6 +1736,11 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         process.stdout.write(command.json ? formatDeltaDoctorJson(result) : formatDeltaDoctorHuman(result));
         return result.exitCode;
       }
+      if (command.target === "pglite") {
+        const result = await runPgliteDoctorCommand({ workspaceRoot: command.workspaceRoot });
+        process.stdout.write(command.json ? formatPgliteDoctorJson(result) : formatPgliteDoctorHuman(result));
+        return result.exitCode;
+      }
       const result = await runDoctorCommand({ workspaceRoot: command.workspaceRoot });
       if (command.json) {
         process.stdout.write(formatDoctorJson(result));
@@ -1930,13 +2003,23 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       return result.exitCode;
     }
     case "agent": {
-      const result = await runAgentCommand(command.options);
-      if (command.options.json) {
-        process.stdout.write(formatAgentJson(result));
-      } else {
-        process.stdout.write(formatAgentHuman(result));
+      const heartbeat = command.options.subcommand === "onboard"
+        ? startCommandHeartbeat({
+            label: `agent onboard ${command.options.target ?? "codex"}`,
+            initialPhase: "prepare-hooks-memory-and-dev-snapshot",
+          })
+        : null;
+      try {
+        const result = await runAgentCommand(command.options);
+        if (command.options.json) {
+          process.stdout.write(formatAgentJson(result));
+        } else {
+          process.stdout.write(formatAgentHuman(result));
+        }
+        return result.exitCode;
+      } finally {
+        heartbeat?.stop();
       }
-      return result.exitCode;
     }
     case "mcp": {
       return runMcpServe(command.workspaceRoot);
@@ -1976,7 +2059,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       });
 
       if (command.json) {
-        process.stdout.write(formatJsonResult(buildGenerateJson(result)));
+        process.stdout.write(formatJsonResult(buildGenerateJson(result, { workspaceRoot: command.workspaceRoot })));
       } else {
         writeHumanGenerate(result);
       }
@@ -1986,7 +2069,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
     case "add": {
       const result = await runAddCommand(command.alias, command.options);
       if (command.options.json) {
-        process.stdout.write(formatJsonResult(buildAddJson(result)));
+        process.stdout.write(formatJsonResult(buildAddJson(result, { workspaceRoot: command.options.workspaceRoot })));
       } else {
         writeHumanAdd(result);
       }
@@ -2022,6 +2105,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
     case "changed": {
       const result = runChangedCommand(command.workspaceRoot, {
         authoredOnly: command.authoredOnly,
+        reviewOnly: command.reviewOnly,
       });
       if (command.json) {
         process.stdout.write(formatJsonResult(result.data));
@@ -2132,11 +2216,12 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       return result.exitCode;
     }
     case "check": {
-      const result = await runCheckCommand(process.cwd(), {
+      const checkWorkspaceRoot = process.cwd();
+      const result = await runCheckCommand(checkWorkspaceRoot, {
         strictSecrets: command.strictSecrets,
       });
       if (command.json) {
-        process.stdout.write(formatJsonResult(buildCheckJson(result)));
+        process.stdout.write(formatJsonResult(buildCheckJson(result, { workspaceRoot: checkWorkspaceRoot })));
       } else {
         writeHumanGenerate(result);
       }
@@ -2286,6 +2371,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         workspaceRoot: command.workspaceRoot,
         db: command.db,
         databaseUrl: command.databaseUrl,
+        local: command.local,
         json: command.json,
       });
 

package/src/forge/cli/db.ts

@@ -7,6 +7,9 @@ import { buildAppGraph } from "../compiler/app-graph/build.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import {
   FORGE_RLS_APPLY_FAILED,
+  FORGE_DB_ADAPTER_UNAVAILABLE,
+  FORGE_PGLITE_STORE_ABORTED,
+  FORGE_PGLITE_STORE_ACTIVE,
   FORGE_RUNTIME_NOT_FOUND,
 } from "../compiler/diagnostics/codes.ts";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
@@ -23,14 +26,20 @@ import {
   resetDatabase,
 } from "../runtime/db/migrate.ts";
 import type { DbAdapterKind } from "../runtime/db/adapter.ts";
+import {
+  DEFAULT_PGLITE_DIR,
+  repairLocalPgliteStore,
+} from "../runtime/db/pglite-adapter.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
-export type DbSubcommand = "diff" | "migrate" | "reset" | "status" | "doctor" | "rls-check";
+export type DbSubcommand = "diff" | "migrate" | "reset" | "status" | "doctor" | "repair" | "rls-check";
 
 export interface DbCommandOptions {
   subcommand: DbSubcommand;
   workspaceRoot: string;
   db: DbAdapterKind;
   databaseUrl?: string;
+  local?: boolean;
   json: boolean;
 }
 
@@ -250,7 +259,7 @@ async function runDbDoctor(
       .sort();
     const ok = inspected.diagnostics.length === 0 && missingTables.length === 0 && missingColumns.length === 0;
 
-    return {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
       ok,
       data: {
         schemaVersion: "0.1.0",
@@ -279,13 +288,92 @@ async function runDbDoctor(
         ...inspected.diagnostics,
       ],
       exitCode: ok ? 0 : 1,
-    };
+    });
   } finally {
     await adapter.close();
   }
 }
 
+async function runDbRepair(options: DbCommandOptions): Promise<DbCommandResult> {
+  if (!options.local) {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+      ok: false,
+      data: {
+        schemaVersion: "0.1.0",
+        repaired: false,
+        adapter: options.db,
+        local: false,
+        nextActions: ["forge db repair --local --adapter pglite --json"],
+      },
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: "FORGE_CLI_USAGE",
+          message: "local database repair requires --local",
+          fixHint: "Pass --local to confirm you want Forge to repair the local development database store.",
+          suggestedCommands: ["forge db repair --local --adapter pglite --json"],
+        }),
+      ],
+      exitCode: 1,
+    });
+  }
+
+  if (options.db !== "pglite") {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+      ok: false,
+      data: {
+        schemaVersion: "0.1.0",
+        repaired: false,
+        adapter: options.db,
+        nextActions: ["forge db repair --local --adapter pglite --json"],
+      },
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: FORGE_DB_ADAPTER_UNAVAILABLE,
+          message: "local repair currently supports only the pglite adapter",
+          fixHint: "Use --adapter pglite for the local Forge dev database store.",
+          suggestedCommands: ["forge db repair --local --adapter pglite --json"],
+        }),
+      ],
+      exitCode: 1,
+    });
+  }
+
+  const dataDir = join(options.workspaceRoot, DEFAULT_PGLITE_DIR);
+  const result = await repairLocalPgliteStore(dataDir);
+  const diagnostics = result.ok
+    ? []
+    : [
+        createDiagnostic({
+          severity: "error",
+          code: result.before.state === "active" ? FORGE_PGLITE_STORE_ACTIVE : FORGE_PGLITE_STORE_ABORTED,
+          message: result.message,
+          fixHint: result.before.state === "active"
+            ? "Stop the running forge dev process before repairing the PGlite store."
+            : "Archive the local PGlite store and retry forge dev, or use --db memory for non-persistent validation.",
+          suggestedCommands: result.nextActions,
+        }),
+      ];
+
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    ok: result.ok,
+    data: {
+      schemaVersion: "0.1.0",
+      adapter: "pglite",
+      local: true,
+      ...result,
+    },
+    diagnostics,
+    exitCode: result.ok ? 0 : 1,
+  });
+}
+
 export async function runDbCommand(options: DbCommandOptions): Promise<DbCommandResult> {
+  if (options.subcommand === "repair") {
+    return runDbRepair(options);
+  }
+
   const { plan, diagnostics: planDiagnostics } = await loadSqlPlan(options.workspaceRoot);
 
   if (!plan) {
@@ -427,7 +515,7 @@ export function formatDbHuman(subcommand: DbSubcommand, result: DbCommandResult)
     return "database reset complete\n";
   }
 
-  if (subcommand === "status" || subcommand === "diff" || subcommand === "doctor") {
+  if (subcommand === "status" || subcommand === "diff" || subcommand === "doctor" || subcommand === "repair") {
     return `${JSON.stringify(result.data, null, 2)}\n`;
   }