Add guarded dev restart handling

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ui/src/api/health.ts

@@ -1,3 +1,17 @@
+export type DevServerHealthStatus = {
+  enabled: true;
+  restartRequired: boolean;
+  reason: "backend_changes" | "pending_migrations" | "backend_changes_and_pending_migrations" | null;
+  lastChangedAt: string | null;
+  changedPathCount: number;
+  changedPathsSample: string[];
+  pendingMigrations: string[];
+  autoRestartEnabled: boolean;
+  activeRunCount: number;
+  waitingForIdle: boolean;
+  lastRestartAt: string | null;
+};
+
 export type HealthStatus = {
   status: "ok";
   version?: string;
@@ -9,6 +23,7 @@ export type HealthStatus = {
   features?: {
     companyDeletionEnabled?: boolean;
   };
+  devServer?: DevServerHealthStatus;
 };
 
 export const healthApi = {

ui/src/components/DevRestartBanner.tsx

@@ -0,0 +1,89 @@
+import { AlertTriangle, RotateCcw, TimerReset } from "lucide-react";
+import type { DevServerHealthStatus } from "../api/health";
+
+function formatRelativeTimestamp(value: string | null): string | null {
+  if (!value) return null;
+  const timestamp = new Date(value).getTime();
+  if (Number.isNaN(timestamp)) return null;
+
+  const deltaMs = Date.now() - timestamp;
+  if (deltaMs < 60_000) return "just now";
+  const deltaMinutes = Math.round(deltaMs / 60_000);
+  if (deltaMinutes < 60) return `${deltaMinutes}m ago`;
+  const deltaHours = Math.round(deltaMinutes / 60);
+  if (deltaHours < 24) return `${deltaHours}h ago`;
+  const deltaDays = Math.round(deltaHours / 24);
+  return `${deltaDays}d ago`;
+}
+
+function describeReason(devServer: DevServerHealthStatus): string {
+  if (devServer.reason === "backend_changes_and_pending_migrations") {
+    return "backend files changed and migrations are pending";
+  }
+  if (devServer.reason === "pending_migrations") {
+    return "pending migrations need a fresh boot";
+  }
+  return "backend files changed since this server booted";
+}
+
+export function DevRestartBanner({ devServer }: { devServer?: DevServerHealthStatus }) {
+  if (!devServer?.enabled || !devServer.restartRequired) return null;
+
+  const changedAt = formatRelativeTimestamp(devServer.lastChangedAt);
+  const sample = devServer.changedPathsSample.slice(0, 3);
+
+  return (
+    <div className="border-b border-amber-300/60 bg-amber-50 text-amber-950 dark:border-amber-500/25 dark:bg-amber-500/10 dark:text-amber-100">
+      <div className="flex flex-col gap-3 px-3 py-2.5 md:flex-row md:items-center md:justify-between">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2 text-[12px] font-semibold uppercase tracking-[0.18em]">
+            <AlertTriangle className="h-3.5 w-3.5 shrink-0" />
+            <span>Restart Required</span>
+            {devServer.autoRestartEnabled ? (
+              <span className="rounded-full bg-amber-900/10 px-2 py-0.5 text-[10px] tracking-[0.14em] dark:bg-amber-100/10">
+                Auto-Restart On
+              </span>
+            ) : null}
+          </div>
+          <p className="mt-1 text-sm">
+            {describeReason(devServer)}
+            {changedAt ? ` · updated ${changedAt}` : ""}
+          </p>
+          <div className="mt-2 flex flex-wrap items-center gap-2 text-xs text-amber-900/80 dark:text-amber-100/75">
+            {sample.length > 0 ? (
+              <span>
+                Changed: {sample.join(", ")}
+                {devServer.changedPathCount > sample.length ? ` +${devServer.changedPathCount - sample.length} more` : ""}
+              </span>
+            ) : null}
+            {devServer.pendingMigrations.length > 0 ? (
+              <span>
+                Pending migrations: {devServer.pendingMigrations.slice(0, 2).join(", ")}
+                {devServer.pendingMigrations.length > 2 ? ` +${devServer.pendingMigrations.length - 2} more` : ""}
+              </span>
+            ) : null}
+          </div>
+        </div>
+
+        <div className="flex shrink-0 items-center gap-2 text-xs font-medium">
+          {devServer.waitingForIdle ? (
+            <div className="inline-flex items-center gap-2 rounded-full bg-amber-900/10 px-3 py-1.5 dark:bg-amber-100/10">
+              <TimerReset className="h-3.5 w-3.5" />
+              <span>Waiting for {devServer.activeRunCount} live run{devServer.activeRunCount === 1 ? "" : "s"} to finish</span>
+            </div>
+          ) : devServer.autoRestartEnabled ? (
+            <div className="inline-flex items-center gap-2 rounded-full bg-amber-900/10 px-3 py-1.5 dark:bg-amber-100/10">
+              <RotateCcw className="h-3.5 w-3.5" />
+              <span>Auto-restart will trigger when the instance is idle</span>
+            </div>
+          ) : (
+            <div className="inline-flex items-center gap-2 rounded-full bg-amber-900/10 px-3 py-1.5 dark:bg-amber-100/10">
+              <RotateCcw className="h-3.5 w-3.5" />
+              <span>Restart `pnpm dev:once` after the active work is safe to interrupt</span>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

ui/src/components/Layout.tsx

@@ -15,6 +15,7 @@ import { NewAgentDialog } from "./NewAgentDialog";
 import { ToastViewport } from "./ToastViewport";
 import { MobileBottomNav } from "./MobileBottomNav";
 import { WorktreeBanner } from "./WorktreeBanner";
+import { DevRestartBanner } from "./DevRestartBanner";
 import { useDialog } from "../context/DialogContext";
 import { usePanel } from "../context/PanelContext";
 import { useCompany } from "../context/CompanyContext";
@@ -78,6 +79,11 @@ export function Layout() {
     queryKey: queryKeys.health,
     queryFn: () => healthApi.get(),
     retry: false,
+    refetchInterval: (query) => {
+      const data = query.state.data as { devServer?: { enabled?: boolean } } | undefined;
+      return data?.devServer?.enabled ? 2000 : false;
+    },
+    refetchIntervalInBackground: true,
   });
 
   useEffect(() => {
@@ -266,6 +272,7 @@ export function Layout() {
         Skip to Main Content
       </a>
       <WorktreeBanner />
+      <DevRestartBanner devServer={health?.devServer} />
       <div className={cn("min-h-0 flex-1", isMobile ? "w-full" : "flex overflow-hidden")}>
         {isMobile && sidebarOpen && (
           <button

ui/src/pages/InstanceExperimentalSettings.tsx

@@ -24,11 +24,14 @@ export function InstanceExperimentalSettings() {
   });
 
   const toggleMutation = useMutation({
-    mutationFn: async (enabled: boolean) =>
-      instanceSettingsApi.updateExperimental({ enableIsolatedWorkspaces: enabled }),
+    mutationFn: async (patch: { enableIsolatedWorkspaces?: boolean; autoRestartDevServerWhenIdle?: boolean }) =>
+      instanceSettingsApi.updateExperimental(patch),
     onSuccess: async () => {
       setActionError(null);
-      await queryClient.invalidateQueries({ queryKey: queryKeys.instance.experimentalSettings });
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: queryKeys.instance.experimentalSettings }),
+        queryClient.invalidateQueries({ queryKey: queryKeys.health }),
+      ]);
     },
     onError: (error) => {
       setActionError(error instanceof Error ? error.message : "Failed to update experimental settings.");
@@ -50,6 +53,7 @@ export function InstanceExperimentalSettings() {
   }
 
   const enableIsolatedWorkspaces = experimentalQuery.data?.enableIsolatedWorkspaces === true;
+  const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;
 
   return (
     <div className="max-w-4xl space-y-6">
@@ -86,7 +90,7 @@ export function InstanceExperimentalSettings() {
               "relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-60",
               enableIsolatedWorkspaces ? "bg-green-600" : "bg-muted",
             )}
-            onClick={() => toggleMutation.mutate(!enableIsolatedWorkspaces)}
+            onClick={() => toggleMutation.mutate({ enableIsolatedWorkspaces: !enableIsolatedWorkspaces })}
           >
             <span
               className={cn(
@@ -97,6 +101,37 @@ export function InstanceExperimentalSettings() {
           </button>
         </div>
       </section>
+
+      <section className="rounded-xl border border-border bg-card p-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="space-y-1.5">
+            <h2 className="text-sm font-semibold">Auto-Restart Dev Server When Idle</h2>
+            <p className="max-w-2xl text-sm text-muted-foreground">
+              In `pnpm dev:once`, wait for all queued and running local agent runs to finish, then restart the server
+              automatically when backend changes or migrations make the current boot stale.
+            </p>
+          </div>
+          <button
+            type="button"
+            aria-label="Toggle guarded dev-server auto-restart"
+            disabled={toggleMutation.isPending}
+            className={cn(
+              "relative inline-flex h-5 w-9 items-center rounded-full transition-colors disabled:cursor-not-allowed disabled:opacity-60",
+              autoRestartDevServerWhenIdle ? "bg-green-600" : "bg-muted",
+            )}
+            onClick={() =>
+              toggleMutation.mutate({ autoRestartDevServerWhenIdle: !autoRestartDevServerWhenIdle })
+            }
+          >
+            <span
+              className={cn(
+                "inline-block h-3.5 w-3.5 rounded-full bg-white transition-transform",
+                autoRestartDevServerWhenIdle ? "translate-x-4.5" : "translate-x-0.5",
+              )}
+            />
+          </button>
+        </div>
+      </section>
     </div>
   );
 }