The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add guarded dev restart handling
dotta8fc399f5112c
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex b39839c1f5..42e70fff64 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -39,6 +39,8 @@ This starts:`pnpm dev` runs the server in watch mode and restarts on changes from workspace packages (including adapter packages). Use `pnpm dev:once` to run without file watching.+`pnpm dev:once` now tracks backend-relevant file changes and pending migrations. When the current boot is stale, the board UI shows a `Restart required` banner. You can also enable guarded auto-restart in `Instance Settings > Experimental`, which waits for queued/running local agent runs to finish before restarting the dev server.+Tailscale/private-auth dev mode:```shdiff --git a/packages/shared/src/types/instance.ts b/packages/shared/src/types/instance.tsindex 3449f46da4..562c55b38d 100644--- a/packages/shared/src/types/instance.ts+++ b/packages/shared/src/types/instance.ts@@ -4,6 +4,7 @@ export interface InstanceGeneralSettings {export interface InstanceExperimentalSettings {enableIsolatedWorkspaces: boolean;+ autoRestartDevServerWhenIdle: boolean;}export interface InstanceSettings {diff --git a/packages/shared/src/validators/instance.ts b/packages/shared/src/validators/instance.tsindex 5511e655a2..05ee432368 100644--- a/packages/shared/src/validators/instance.ts+++ b/packages/shared/src/validators/instance.ts@@ -8,6 +8,7 @@ export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.export const instanceExperimentalSettingsSchema = z.object({enableIsolatedWorkspaces: z.boolean().default(false),+ autoRestartDevServerWhenIdle: z.boolean().default(false),}).strict();export const patchInstanceExperimentalSettingsSchema = instanceExperimentalSettingsSchema.partial();diff --git a/scripts/dev-runner.mjs b/scripts/dev-runner.mjsindex 391ddb44df..3df034e0ad 100644--- a/scripts/dev-runner.mjs+++ b/scripts/dev-runner.mjs@@ -1,10 +1,54 @@#!/usr/bin/env nodeimport { spawn } from "node:child_process";+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";+import path from "node:path";import { createInterface } from "node:readline/promises";import { stdin, stdout } from "node:process";+import { fileURLToPath } from "node:url";const mode = process.argv[2] === "watch" ? "watch" : "dev";const cliArgs = process.argv.slice(3);+const scanIntervalMs = 1500;+const autoRestartPollIntervalMs = 2500;+const gracefulShutdownTimeoutMs = 10_000;+const changedPathSampleLimit = 5;+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");+const devServerStatusFilePath = path.join(repoRoot, ".paperclip", "dev-server-status.json");++const watchedDirectories = [+ ".paperclip",+ "cli",+ "scripts",+ "server",+ "packages/adapter-utils",+ "packages/adapters",+ "packages/db",+ "packages/plugins/sdk",+ "packages/shared",+].map((relativePath) => path.join(repoRoot, relativePath));++const watchedFiles = [+ ".env",+ "package.json",+ "pnpm-workspace.yaml",+ "tsconfig.base.json",+ "tsconfig.json",+ "vitest.config.ts",+].map((relativePath) => path.join(repoRoot, relativePath));++const ignoredDirectoryNames = new Set([+ ".git",+ ".turbo",+ ".vite",+ "coverage",+ "dist",+ "node_modules",+ "ui-dist",+]);++const ignoredRelativePaths = new Set([+ ".paperclip/dev-server-status.json",+]);const tailscaleAuthFlagNames = new Set(["--tailscale-auth",@@ -34,6 +78,10 @@ const env = {PAPERCLIP_UI_DEV_MIDDLEWARE: "true",};+if (mode === "dev") {+ env.PAPERCLIP_DEV_SERVER_STATUS_FILE = devServerStatusFilePath;+}+if (mode === "watch") {env.PAPERCLIP_MIGRATION_PROMPT ??= "never";env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";@@ -50,6 +98,19 @@ if (tailscaleAuth) {}const pnpmBin = process.platform === "win32" ? "pnpm.cmd" : "pnpm";+let previousSnapshot = collectWatchedSnapshot();+let dirtyPaths = new Set();+let pendingMigrations = [];+let lastChangedAt = null;+let lastRestartAt = null;+let scanInFlight = false;+let restartInFlight = false;+let shuttingDown = false;+let childExitWasExpected = false;+let child = null;+let childExitPromise = null;+let scanTimer = null;+let autoRestartTimer = null;function toError(error, context = "Dev runner command failed") {if (error instanceof Error) return error;@@ -82,9 +143,110 @@ function formatPendingMigrationSummary(migrations) {: migrations.join(", ");}+function exitForSignal(signal) {+ if (signal === "SIGINT") {+ process.exit(130);+ }+ if (signal === "SIGTERM") {+ process.exit(143);+ }+ process.exit(1);+}++function toRelativePath(absolutePath) {+ return path.relative(repoRoot, absolutePath).split(path.sep).join("/");+}++function readSignature(absolutePath) {+ const stats = statSync(absolutePath);+ return `${Math.trunc(stats.mtimeMs)}:${stats.size}`;+}++function addFileToSnapshot(snapshot, absolutePath) {+ const relativePath = toRelativePath(absolutePath);+ if (ignoredRelativePaths.has(relativePath)) return;+ snapshot.set(relativePath, readSignature(absolutePath));+}++function walkDirectory(snapshot, absoluteDirectory) {+ if (!existsSync(absoluteDirectory)) return;++ for (const entry of readdirSync(absoluteDirectory, { withFileTypes: true })) {+ if (ignoredDirectoryNames.has(entry.name)) continue;++ const absolutePath = path.join(absoluteDirectory, entry.name);+ if (entry.isDirectory()) {+ walkDirectory(snapshot, absolutePath);+ continue;+ }+ if (entry.isFile() || entry.isSymbolicLink()) {+ addFileToSnapshot(snapshot, absolutePath);+ }+ }+}++function collectWatchedSnapshot() {+ const snapshot = new Map();++ for (const absoluteDirectory of watchedDirectories) {+ walkDirectory(snapshot, absoluteDirectory);+ }+ for (const absoluteFile of watchedFiles) {+ if (!existsSync(absoluteFile)) continue;+ addFileToSnapshot(snapshot, absoluteFile);+ }++ return snapshot;+}++function diffSnapshots(previous, next) {+ const changed = new Set();++ for (const [relativePath, signature] of next) {+ if (previous.get(relativePath) !== signature) {+ changed.add(relativePath);+ }+ }+ for (const relativePath of previous.keys()) {+ if (!next.has(relativePath)) {+ changed.add(relativePath);+ }+ }++ return [...changed].sort();+}++function ensureDevStatusDirectory() {+ mkdirSync(path.dirname(devServerStatusFilePath), { recursive: true });+}++function writeDevServerStatus() {+ if (mode !== "dev") return;++ ensureDevStatusDirectory();+ const changedPaths = [...dirtyPaths].sort();+ writeFileSync(+ devServerStatusFilePath,+ `${JSON.stringify({+ dirty: changedPaths.length > 0 || pendingMigrations.length > 0,+ lastChangedAt,+ changedPathCount: changedPaths.length,+ changedPathsSample: changedPaths.slice(0, changedPathSampleLimit),+ pendingMigrations,+ lastRestartAt,+ }, null, 2)}\n`,+ "utf8",+ );+}++function clearDevServerStatus() {+ if (mode !== "dev") return;+ rmSync(devServerStatusFilePath, { force: true });+}+async function runPnpm(args, options = {}) {return await new Promise((resolve, reject) => {- const child = spawn(pnpmBin, args, {+ const spawned = spawn(pnpmBin, args, {stdio: options.stdio ?? ["ignore", "pipe", "pipe"],env: options.env ?? process.env,shell: process.platform === "win32",@@ -93,19 +255,19 @@ async function runPnpm(args, options = {}) {let stdoutBuffer = "";let stderrBuffer = "";- if (child.stdout) {- child.stdout.on("data", (chunk) => {+ if (spawned.stdout) {+ spawned.stdout.on("data", (chunk) => {stdoutBuffer += String(chunk);});}- if (child.stderr) {- child.stderr.on("data", (chunk) => {+ if (spawned.stderr) {+ spawned.stderr.on("data", (chunk) => {stderrBuffer += String(chunk);});}- child.on("error", reject);- child.on("exit", (code, signal) => {+ spawned.on("error", reject);+ spawned.on("exit", (code, signal) => {resolve({code: code ?? 0,signal,@@ -116,9 +278,7 @@ async function runPnpm(args, options = {}) {});}-async function maybePreflightMigrations() {- if (mode !== "watch") return;-+async function getMigrationStatusPayload() {const status = await runPnpm(["--filter", "@paperclipai/db", "exec", "tsx", "src/migration-status.ts", "--json"],{ env },@@ -132,9 +292,8 @@ async function maybePreflightMigrations() {process.exit(status.code);}- let payload;try {- payload = JSON.parse(status.stdout.trim());+ return JSON.parse(status.stdout.trim());} catch (error) {process.stderr.write(status.stderr ||@@ -143,15 +302,31 @@ async function maybePreflightMigrations() {);throw toError(error, "Unable to parse migration-status JSON output");}+}++async function refreshPendingMigrations() {+ const payload = await getMigrationStatusPayload();+ pendingMigrations =+ payload.status === "needsMigrations" && Array.isArray(payload.pendingMigrations)+ ? payload.pendingMigrations.filter((entry) => typeof entry === "string" && entry.trim().length > 0)+ : [];+ writeDevServerStatus();+ return payload;+}++async function maybePreflightMigrations(options = {}) {+ const interactive = options.interactive ?? mode === "watch";+ const autoApply = options.autoApply ?? env.PAPERCLIP_MIGRATION_AUTO_APPLY === "true";+ const exitOnDecline = options.exitOnDecline ?? mode === "watch";- if (payload.status !== "needsMigrations" || payload.pendingMigrations.length === 0) {+ const payload = await refreshPendingMigrations();+ if (payload.status !== "needsMigrations" || pendingMigrations.length === 0) {return;}- const autoApply = env.PAPERCLIP_MIGRATION_AUTO_APPLY === "true";let shouldApply = autoApply;- if (!autoApply) {+ if (!autoApply && interactive) {if (!stdin.isTTY || !stdout.isTTY) {shouldApply = true;} else {@@ -159,7 +334,7 @@ async function maybePreflightMigrations() {try {const answer = (await prompt.question(- `Apply pending migrations (${formatPendingMigrationSummary(payload.pendingMigrations)}) now? (y/N): `,+ `Apply pending migrations (${formatPendingMigrationSummary(pendingMigrations)}) now? (y/N): `,)).trim()@@ -172,11 +347,14 @@ async function maybePreflightMigrations() {}if (!shouldApply) {- process.stderr.write(- `[paperclip] Pending migrations detected (${formatPendingMigrationSummary(payload.pendingMigrations)}). ` +- "Refusing to start watch mode against a stale schema.\n",- );- process.exit(1);+ if (exitOnDecline) {+ process.stderr.write(+ `[paperclip] Pending migrations detected (${formatPendingMigrationSummary(pendingMigrations)}). ` ++ "Refusing to start watch mode against a stale schema.\n",+ );+ process.exit(1);+ }+ return;}const migrate = spawn(pnpmBin, ["db:migrate"], {@@ -188,15 +366,15 @@ async function maybePreflightMigrations() {migrate.on("exit", (code, signal) => resolve({ code: code ?? 0, signal }));});if (exit.signal) {- process.kill(process.pid, exit.signal);+ exitForSignal(exit.signal);return;}if (exit.code !== 0) {process.exit(exit.code);}-}-await maybePreflightMigrations();+ await refreshPendingMigrations();+}async function buildPluginSdk() {console.log("[paperclip] building plugin sdk...");@@ -205,7 +383,7 @@ async function buildPluginSdk() {{ stdio: "inherit" },);if (result.signal) {- process.kill(process.pid, result.signal);+ exitForSignal(result.signal);return;}if (result.code !== 0) {@@ -214,19 +392,192 @@ async function buildPluginSdk() {}}-await buildPluginSdk();+async function markChildAsCurrent() {+ previousSnapshot = collectWatchedSnapshot();+ dirtyPaths = new Set();+ lastChangedAt = null;+ lastRestartAt = new Date().toISOString();+ await refreshPendingMigrations();+}-const serverScript = mode === "watch" ? "dev:watch" : "dev";-const child = spawn(- pnpmBin,- ["--filter", "@paperclipai/server", serverScript, ...forwardedArgs],- { stdio: "inherit", env, shell: process.platform === "win32" },-);+async function scanForBackendChanges() {+ if (mode !== "dev" || scanInFlight || restartInFlight) return;+ scanInFlight = true;+ try {+ const nextSnapshot = collectWatchedSnapshot();+ const changed = diffSnapshots(previousSnapshot, nextSnapshot);+ previousSnapshot = nextSnapshot;+ if (changed.length === 0) return;-child.on("exit", (code, signal) => {- if (signal) {- process.kill(process.pid, signal);+ for (const relativePath of changed) {+ dirtyPaths.add(relativePath);+ }+ lastChangedAt = new Date().toISOString();+ await refreshPendingMigrations();+ } finally {+ scanInFlight = false;+ }+}++async function getDevHealthPayload() {+ const serverPort = env.PORT ?? process.env.PORT ?? "3100";+ const response = await fetch(`http://127.0.0.1:${serverPort}/api/health`);+ if (!response.ok) {+ throw new Error(`Health request failed (${response.status})`);+ }+ return await response.json();+}++async function waitForChildExit() {+ if (!childExitPromise) {+ return { code: 0, signal: null };+ }+ return await childExitPromise;+}++async function stopChildForRestart() {+ if (!child) return { code: 0, signal: null };+ childExitWasExpected = true;+ child.kill("SIGTERM");+ const killTimer = setTimeout(() => {+ if (child) {+ child.kill("SIGKILL");+ }+ }, gracefulShutdownTimeoutMs);+ try {+ return await waitForChildExit();+ } finally {+ clearTimeout(killTimer);+ }+}++async function startServerChild() {+ await buildPluginSdk();++ const serverScript = mode === "watch" ? "dev:watch" : "dev";+ child = spawn(+ pnpmBin,+ ["--filter", "@paperclipai/server", serverScript, ...forwardedArgs],+ { stdio: "inherit", env, shell: process.platform === "win32" },+ );++ childExitPromise = new Promise((resolve, reject) => {+ child.on("error", reject);+ child.on("exit", (code, signal) => {+ const expected = childExitWasExpected;+ childExitWasExpected = false;+ child = null;+ childExitPromise = null;+ resolve({ code: code ?? 0, signal });++ if (restartInFlight || expected || shuttingDown) {+ return;+ }+ if (signal) {+ exitForSignal(signal);+ return;+ }+ process.exit(code ?? 0);+ });+ });++ await markChildAsCurrent();+}++async function maybeAutoRestartChild() {+ if (mode !== "dev" || restartInFlight || !child) return;+ if (dirtyPaths.size === 0 && pendingMigrations.length === 0) return;++ let health;+ try {+ health = await getDevHealthPayload();+ } catch {+ return;+ }++ const devServer = health?.devServer;+ if (!devServer?.enabled || devServer.autoRestartEnabled !== true) return;+ if ((devServer.activeRunCount ?? 0) > 0) return;++ try {+ restartInFlight = true;+ await maybePreflightMigrations({+ autoApply: true,+ interactive: false,+ exitOnDecline: false,+ });+ await stopChildForRestart();+ await startServerChild();+ } catch (error) {+ const err = toError(error, "Auto-restart failed");+ process.stderr.write(`${err.stack ?? err.message}\n`);+ process.exit(1);+ } finally {+ restartInFlight = false;+ }+}++function installDevIntervals() {+ if (mode !== "dev") return;++ scanTimer = setInterval(() => {+ void scanForBackendChanges();+ }, scanIntervalMs);+ autoRestartTimer = setInterval(() => {+ void maybeAutoRestartChild();+ }, autoRestartPollIntervalMs);+}++function clearDevIntervals() {+ if (scanTimer) {+ clearInterval(scanTimer);+ scanTimer = null;+ }+ if (autoRestartTimer) {+ clearInterval(autoRestartTimer);+ autoRestartTimer = null;+ }+}++async function shutdown(signal) {+ if (shuttingDown) return;+ shuttingDown = true;+ clearDevIntervals();+ clearDevServerStatus();++ if (!child) {+ if (signal) {+ exitForSignal(signal);+ return;+ }+ process.exit(0);+ }++ childExitWasExpected = true;+ child.kill(signal);+ const exit = await waitForChildExit();+ if (exit.signal) {+ exitForSignal(exit.signal);return;}- process.exit(code ?? 0);+ process.exit(exit.code ?? 0);+}++process.on("SIGINT", () => {+ void shutdown("SIGINT");});+process.on("SIGTERM", () => {+ void shutdown("SIGTERM");+});++await maybePreflightMigrations();+await startServerChild();+installDevIntervals();++if (mode === "watch") {+ const exit = await waitForChildExit();+ if (exit.signal) {+ exitForSignal(exit.signal);+ }+ process.exit(exit.code ?? 0);+}diff --git a/server/src/__tests__/dev-server-status.test.ts b/server/src/__tests__/dev-server-status.test.tsnew file mode 100644index 0000000000..d178f94139--- /dev/null+++ b/server/src/__tests__/dev-server-status.test.ts@@ -0,0 +1,66 @@+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import os from "node:os";+import path from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import { readPersistedDevServerStatus, toDevServerHealthStatus } from "../dev-server-status.js";++const tempDirs = [];++function createTempStatusFile(payload: unknown) {+ const dir = mkdtempSync(path.join(os.tmpdir(), "paperclip-dev-status-"));+ tempDirs.push(dir);+ const filePath = path.join(dir, "dev-server-status.json");+ writeFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf8");+ return filePath;+}++afterEach(() => {+ for (const dir of tempDirs.splice(0)) {+ rmSync(dir, { recursive: true, force: true });+ }+});++describe("dev server status helpers", () => {+ it("reads and normalizes persisted supervisor state", () => {+ const filePath = createTempStatusFile({+ dirty: true,+ lastChangedAt: "2026-03-20T12:00:00.000Z",+ changedPathCount: 4,+ changedPathsSample: ["server/src/app.ts", "packages/shared/src/index.ts"],+ pendingMigrations: ["0040_restart_banner.sql"],+ lastRestartAt: "2026-03-20T11:30:00.000Z",+ });++ expect(readPersistedDevServerStatus({ PAPERCLIP_DEV_SERVER_STATUS_FILE: filePath })).toEqual({+ dirty: true,+ lastChangedAt: "2026-03-20T12:00:00.000Z",+ changedPathCount: 4,+ changedPathsSample: ["server/src/app.ts", "packages/shared/src/index.ts"],+ pendingMigrations: ["0040_restart_banner.sql"],+ lastRestartAt: "2026-03-20T11:30:00.000Z",+ });+ });++ it("derives waiting-for-idle health state", () => {+ const health = toDevServerHealthStatus(+ {+ dirty: true,+ lastChangedAt: "2026-03-20T12:00:00.000Z",+ changedPathCount: 2,+ changedPathsSample: ["server/src/app.ts"],+ pendingMigrations: [],+ lastRestartAt: "2026-03-20T11:30:00.000Z",+ },+ { autoRestartEnabled: true, activeRunCount: 3 },+ );++ expect(health).toMatchObject({+ enabled: true,+ restartRequired: true,+ reason: "backend_changes",+ autoRestartEnabled: true,+ activeRunCount: 3,+ waitingForIdle: true,+ });+ });+});diff --git a/server/src/__tests__/instance-settings-routes.test.ts b/server/src/__tests__/instance-settings-routes.test.tsindex 8b56fd67b5..9668d1bfb9 100644--- a/server/src/__tests__/instance-settings-routes.test.ts+++ b/server/src/__tests__/instance-settings-routes.test.ts@@ -38,6 +38,7 @@ describe("instance settings routes", () => {});mockInstanceSettingsService.getExperimental.mockResolvedValue({enableIsolatedWorkspaces: false,+ autoRestartDevServerWhenIdle: false,});mockInstanceSettingsService.updateGeneral.mockResolvedValue({id: "instance-settings-1",@@ -49,6 +50,7 @@ describe("instance settings routes", () => {id: "instance-settings-1",experimental: {enableIsolatedWorkspaces: true,+ autoRestartDevServerWhenIdle: false,},});mockInstanceSettingsService.listCompanyIds.mockResolvedValue(["company-1", "company-2"]);@@ -64,7 +66,10 @@ describe("instance settings routes", () => {const getRes = await request(app).get("/api/instance/settings/experimental");expect(getRes.status).toBe(200);- expect(getRes.body).toEqual({ enableIsolatedWorkspaces: false });+ expect(getRes.body).toEqual({+ enableIsolatedWorkspaces: false,+ autoRestartDevServerWhenIdle: false,+ });const patchRes = await request(app).patch("/api/instance/settings/experimental")@@ -77,6 +82,24 @@ describe("instance settings routes", () => {expect(mockLogActivity).toHaveBeenCalledTimes(2);});+ it("allows local board users to update guarded dev-server auto-restart", async () => {+ const app = createApp({+ type: "board",+ userId: "local-board",+ source: "local_implicit",+ isInstanceAdmin: true,+ });++ await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ autoRestartDevServerWhenIdle: true })+ .expect(200);++ expect(mockInstanceSettingsService.updateExperimental).toHaveBeenCalledWith({+ autoRestartDevServerWhenIdle: true,+ });+ });+it("allows local board users to read and update general settings", async () => {const app = createApp({type: "board",diff --git a/server/src/dev-server-status.ts b/server/src/dev-server-status.tsnew file mode 100644index 0000000000..aecb0fc985--- /dev/null+++ b/server/src/dev-server-status.ts@@ -0,0 +1,103 @@+import { existsSync, readFileSync } from "node:fs";++export type PersistedDevServerStatus = {+ dirty: boolean;+ lastChangedAt: string | null;+ changedPathCount: number;+ changedPathsSample: string[];+ pendingMigrations: string[];+ lastRestartAt: string | null;+};++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;+};++function normalizeStringArray(value: unknown): string[] {+ if (!Array.isArray(value)) return [];+ return value+ .filter((entry): entry is string => typeof entry === "string")+ .map((entry) => entry.trim())+ .filter((entry) => entry.length > 0);+}++function normalizeTimestamp(value: unknown): string | null {+ if (typeof value !== "string") return null;+ const trimmed = value.trim();+ return trimmed.length > 0 ? trimmed : null;+}++export function readPersistedDevServerStatus(+ env: NodeJS.ProcessEnv = process.env,+): PersistedDevServerStatus | null {+ const filePath = env.PAPERCLIP_DEV_SERVER_STATUS_FILE?.trim();+ if (!filePath || !existsSync(filePath)) return null;++ try {+ const raw = JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;+ const changedPathsSample = normalizeStringArray(raw.changedPathsSample).slice(0, 5);+ const pendingMigrations = normalizeStringArray(raw.pendingMigrations);+ const changedPathCountRaw = raw.changedPathCount;+ const changedPathCount =+ typeof changedPathCountRaw === "number" && Number.isFinite(changedPathCountRaw)+ ? Math.max(0, Math.trunc(changedPathCountRaw))+ : changedPathsSample.length;+ const dirtyRaw = raw.dirty;+ const dirty =+ typeof dirtyRaw === "boolean"+ ? dirtyRaw+ : changedPathCount > 0 || pendingMigrations.length > 0;++ return {+ dirty,+ lastChangedAt: normalizeTimestamp(raw.lastChangedAt),+ changedPathCount,+ changedPathsSample,+ pendingMigrations,+ lastRestartAt: normalizeTimestamp(raw.lastRestartAt),+ };+ } catch {+ return null;+ }+}++export function toDevServerHealthStatus(+ persisted: PersistedDevServerStatus,+ opts: { autoRestartEnabled: boolean; activeRunCount: number },+): DevServerHealthStatus {+ const hasPathChanges = persisted.changedPathCount > 0;+ const hasPendingMigrations = persisted.pendingMigrations.length > 0;+ const reason =+ hasPathChanges && hasPendingMigrations+ ? "backend_changes_and_pending_migrations"+ : hasPendingMigrations+ ? "pending_migrations"+ : hasPathChanges+ ? "backend_changes"+ : null;+ const restartRequired = persisted.dirty || reason !== null;++ return {+ enabled: true,+ restartRequired,+ reason,+ lastChangedAt: persisted.lastChangedAt,+ changedPathCount: persisted.changedPathCount,+ changedPathsSample: persisted.changedPathsSample,+ pendingMigrations: persisted.pendingMigrations,+ autoRestartEnabled: opts.autoRestartEnabled,+ activeRunCount: opts.activeRunCount,+ waitingForIdle: restartRequired && opts.autoRestartEnabled && opts.activeRunCount > 0,+ lastRestartAt: persisted.lastRestartAt,+ };+}diff --git a/server/src/routes/health.ts b/server/src/routes/health.tsindex 59897a89d4..0bf6e92fe5 100644--- a/server/src/routes/health.ts+++ b/server/src/routes/health.ts@@ -1,8 +1,10 @@import { Router } from "express";import type { Db } from "@paperclipai/db";-import { and, count, eq, gt, isNull, sql } from "drizzle-orm";-import { instanceUserRoles, invites } from "@paperclipai/db";+import { and, count, eq, gt, inArray, isNull, sql } from "drizzle-orm";+import { heartbeatRuns, instanceUserRoles, invites } from "@paperclipai/db";import type { DeploymentExposure, DeploymentMode } from "@paperclipai/shared";+import { readPersistedDevServerStatus, toDevServerHealthStatus } from "../dev-server-status.js";+import { instanceSettingsService } from "../services/instance-settings.js";import { serverVersion } from "../version.js";export function healthRoutes(@@ -55,6 +57,23 @@ export function healthRoutes(}}+ const persistedDevServerStatus = readPersistedDevServerStatus();+ let devServer: ReturnType<typeof toDevServerHealthStatus> | undefined;+ if (persistedDevServerStatus) {+ const instanceSettings = instanceSettingsService(db);+ const experimentalSettings = await instanceSettings.getExperimental();+ const activeRunCount = await db+ .select({ count: count() })+ .from(heartbeatRuns)+ .where(inArray(heartbeatRuns.status, ["queued", "running"]))+ .then((rows) => Number(rows[0]?.count ?? 0));++ devServer = toDevServerHealthStatus(persistedDevServerStatus, {+ autoRestartEnabled: experimentalSettings.autoRestartDevServerWhenIdle ?? false,+ activeRunCount,+ });+ }+res.json({status: "ok",version: serverVersion,@@ -66,6 +85,7 @@ export function healthRoutes(features: {companyDeletionEnabled: opts.companyDeletionEnabled,},+ ...(devServer ? { devServer } : {}),});});diff --git a/server/src/services/instance-settings.ts b/server/src/services/instance-settings.tsindex bbc4df3d80..ccefea7c90 100644--- a/server/src/services/instance-settings.ts+++ b/server/src/services/instance-settings.ts@@ -30,10 +30,12 @@ function normalizeExperimentalSettings(raw: unknown): InstanceExperimentalSettinif (parsed.success) {return {enableIsolatedWorkspaces: parsed.data.enableIsolatedWorkspaces ?? false,+ autoRestartDevServerWhenIdle: parsed.data.autoRestartDevServerWhenIdle ?? false,};}return {enableIsolatedWorkspaces: false,+ autoRestartDevServerWhenIdle: false,};}diff --git a/ui/src/api/health.ts b/ui/src/api/health.tsindex b1573805a2..e2725b209d 100644--- a/ui/src/api/health.ts+++ b/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 = {diff --git a/ui/src/components/DevRestartBanner.tsx b/ui/src/components/DevRestartBanner.tsxnew file mode 100644index 0000000000..5f8ba8a0a5--- /dev/null+++ b/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>+ );+}diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsxindex 8bae6920cf..8761b71c9b 100644--- a/ui/src/components/Layout.tsx+++ b/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 && (<buttondiff --git a/ui/src/pages/InstanceExperimentalSettings.tsx b/ui/src/pages/InstanceExperimentalSettings.tsxindex ac04ae0767..236d45448e 100644--- a/ui/src/pages/InstanceExperimentalSettings.tsx+++ b/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 })}><spanclassName={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>);}