ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
fix: start agent maintenance only in the guarded runtime phase
Juan Denisac0871c01603
diff --git a/backend/app/bootstrap/agents.py b/backend/app/bootstrap/agents.pynew file mode 100644index 00000000..6c01d137--- /dev/null+++ b/backend/app/bootstrap/agents.py@@ -0,0 +1,14 @@+"""Process-local agent maintenance starts only in the server runtime."""+++def start_agent_runtime(app):+ if app.config.get('TESTING'):+ return++ from app.services.agent_registry import agent_registry+ from app.services.nonce_service import nonce_service+ from app.services.anomaly_detection_service import anomaly_detection_service++ agent_registry.start(app)+ nonce_service.start_cleanup()+ anomaly_detection_service.start_cleanup()diff --git a/backend/app/bootstrap/runtime.py b/backend/app/bootstrap/runtime.pyindex 915bc6da..d03908a4 100644--- a/backend/app/bootstrap/runtime.py+++ b/backend/app/bootstrap/runtime.py@@ -29,6 +29,9 @@ def start_runtime(app):import logginglogging.getLogger(__name__).exception('Interrupted-job recovery failed')+ from app.bootstrap.agents import start_agent_runtime+ start_agent_runtime(app)+# Start metrics history collection in backgroundfrom app.services.metrics_history_service import MetricsHistoryServiceif not MetricsHistoryService.is_running():diff --git a/backend/app/jobs/thread_ownership.py b/backend/app/jobs/thread_ownership.pyindex ec25824c..dde1b9ff 100644--- a/backend/app/jobs/thread_ownership.py+++ b/backend/app/jobs/thread_ownership.py@@ -89,7 +89,7 @@ THREAD_OWNERSHIP = {'lifecycle': LIFECYCLE_PROCESS_LOOP,'rationale': 'Long-lived liveness checker for connected agents.',},- 'app/services/anomaly_detection_service.py:__init__:self._cleanup_loop': {+ 'app/services/anomaly_detection_service.py:start_cleanup:self._cleanup_loop': {'owner': 'anomaly detector','lifecycle': LIFECYCLE_PROCESS_LOOP,'rationale': 'Maintains process-local anomaly detector state and retention.',@@ -134,7 +134,7 @@ THREAD_OWNERSHIP = {'lifecycle': LIFECYCLE_PROCESS_LOOP,'rationale': 'Long-lived monitor loop; periodic migration is separate from one-shot work.',},- 'app/services/nonce_service.py:__init__:self._cleanup_loop': {+ 'app/services/nonce_service.py:start_cleanup:self._cleanup_loop': {'owner': 'nonce store','lifecycle': LIFECYCLE_PROCESS_LOOP,'rationale': 'Expires process-local nonce state.',diff --git a/backend/app/services/agent_registry.py b/backend/app/services/agent_registry.pyindex 74e3ec4c..98162e0a 100644--- a/backend/app/services/agent_registry.py+++ b/backend/app/services/agent_registry.py@@ -188,7 +188,10 @@ class AgentRegistry:# Called outside an app context (e.g. during testing) —# heartbeat checker will skip DB operations gracefully.self._app = None- # Start heartbeat checker++ def start(self, app):+ """Start liveness checks after application persistence is ready."""+ self._app = appself._start_heartbeat_checker()def _start_heartbeat_checker(self):diff --git a/backend/app/services/anomaly_detection_service.py b/backend/app/services/anomaly_detection_service.pyindex 6245f0b9..0ae3ce6e 100644--- a/backend/app/services/anomaly_detection_service.py+++ b/backend/app/services/anomaly_detection_service.py@@ -60,8 +60,14 @@ class AnomalyDetectionService:self._lock = threading.Lock()- # Start cleanup threadself._stop_cleanup = threading.Event()+ self._cleanup_thread = None++ def start_cleanup(self):+ """Start retention once, from the application runtime phase."""+ if self._cleanup_thread and self._cleanup_thread.is_alive():+ return+ self._stop_cleanup.clear()self._cleanup_thread = threading.Thread(target=self._cleanup_loop,daemon=Truediff --git a/backend/app/services/nonce_service.py b/backend/app/services/nonce_service.pyindex b6efa22b..df0353e8 100644--- a/backend/app/services/nonce_service.py+++ b/backend/app/services/nonce_service.py@@ -42,8 +42,14 @@ class NonceService:# TTL for nonces (5 minutes)self._ttl = 300- # Start cleanup threadself._stop_cleanup = threading.Event()+ self._cleanup_thread = None++ def start_cleanup(self):+ """Start retention once, from the application runtime phase."""+ if self._cleanup_thread and self._cleanup_thread.is_alive():+ return+ self._stop_cleanup.clear()self._cleanup_thread = threading.Thread(target=self._cleanup_loop,daemon=Truediff --git a/backend/tests/test_bootstrap_boundaries.py b/backend/tests/test_bootstrap_boundaries.pyindex 2aeb5512..a3f2c47e 100644--- a/backend/tests/test_bootstrap_boundaries.py+++ b/backend/tests/test_bootstrap_boundaries.py@@ -22,6 +22,7 @@ def runtime_calls(monkeypatch):modules = {'app.jobs.service': {'JobService': SimpleNamespace(recover_interrupted=record('recover'))},+ 'app.bootstrap.agents': {'start_agent_runtime': record('agents')},'app.services.metrics_history_service': {'MetricsHistoryService': SimpleNamespace(is_running=lambda: False, start_collection=record('metrics'))},'app.queue_bus.consumers': {'start_webhook_consumer': record('webhooks')},@@ -57,52 +58,11 @@ def test_one_shot_startup_never_recovers_or_starts_workers(monkeypatch, runtime_def test_recovery_precedes_consumers_and_handlers_precede_jobs(monkeypatch, runtime_calls, argv):monkeypatch.setattr(sys, 'argv', argv)runtime.start_runtime(SimpleNamespace(config={}, logger=Mock()))- assert runtime_calls == ['recover', 'metrics', 'webhooks', 'notifications',+ assert runtime_calls == ['recover', 'agents', 'metrics', 'webhooks', 'notifications','analytics', 'handlers', 'jobs', 'monitoring','uptime', 'linked', 'relay'][email protected]('failed_phase', [None, 'persistence', 'plugins'])-def test_factory_phase_order_and_context(monkeypatch, failed_phase):- import app as application- from flask import has_app_context- from app.bootstrap import configuration, persistence, plugins, http- import app.sockets- import app.agent_gateway- import app.core_blueprints- from app.services import recycle_bin_service, restore_point_adapters-- calls = []- def phase(name, context=False):- def run(*args):- assert has_app_context() is context- calls.append(name)- if name == failed_phase:- raise RuntimeError('startup failed')- return run-- monkeypatch.setattr(configuration, 'configure_application', phase('configuration'))- monkeypatch.setattr(app.sockets, 'init_socketio', phase('socket'))- monkeypatch.setattr(app.agent_gateway, 'init_agent_gateway', phase('gateway'))- monkeypatch.setattr(app.core_blueprints, 'register_core_blueprints', phase('routes'))- monkeypatch.setattr(recycle_bin_service, 'register_builtin_types', phase('recycle'))- monkeypatch.setattr(restore_point_adapters, 'register_builtin_restore_point_adapters', phase('restore'))- monkeypatch.setattr(persistence, 'prepare_persistence', phase('persistence', True))- monkeypatch.setattr(plugins, 'load_extensions', phase('plugins', True))- monkeypatch.setattr(runtime, 'start_runtime', phase('runtime', True))- monkeypatch.setattr(http, 'register_http_handlers', phase('http'))- monkeypatch.setattr(application, 'socketio', application.socketio)- expected = ['configuration', 'socket', 'gateway', 'routes', 'recycle',- 'restore', 'persistence', 'plugins', 'runtime', 'http']- if failed_phase:- with pytest.raises(RuntimeError, match='startup failed'):- application.create_app('testing')- assert calls == expected[:expected.index(failed_phase) + 1]- else:- application.create_app('testing')- assert calls == expected--def test_monitor_failure_does_not_prevent_other_runtime_services(runtime_calls):def fail(_app):raise RuntimeError('monitor unavailable')@@ -113,6 +73,57 @@ def test_monitor_failure_does_not_prevent_other_runtime_services(runtime_calls):assert runtime_calls[-3:] == ['uptime', 'linked', 'relay']+def test_agent_maintenance_runs_only_in_server_mode(monkeypatch):+ from app.bootstrap.agents import start_agent_runtime+ from app.services.agent_registry import agent_registry+ from app.services.nonce_service import nonce_service+ from app.services.anomaly_detection_service import anomaly_detection_service++ heartbeat, nonces, anomalies = Mock(), Mock(), Mock()+ monkeypatch.setattr(agent_registry, 'start', heartbeat)+ monkeypatch.setattr(nonce_service, 'start_cleanup', nonces)+ monkeypatch.setattr(anomaly_detection_service, 'start_cleanup', anomalies)+ start_agent_runtime(SimpleNamespace(config={'TESTING': True}))+ assert not any(call.called for call in (heartbeat, nonces, anomalies))+ server = SimpleNamespace(config={})+ start_agent_runtime(server)+ heartbeat.assert_called_once_with(server)+ nonces.assert_called_once_with()+ anomalies.assert_called_once_with()++[email protected]('module_name,instance_name', [+ ('nonce_service', 'nonce_service'),+ ('anomaly_detection_service', 'anomaly_detection_service'),+])+def test_agent_cleanup_start_is_idempotent(monkeypatch, module_name, instance_name):+ import importlib+ import threading+ module = importlib.import_module(f'app.services.{module_name}')+ service = getattr(module, instance_name)+ thread = Mock()+ thread.is_alive.return_value = True+ constructor = Mock(return_value=thread)+ monkeypatch.setattr(service, '_cleanup_thread', None)+ monkeypatch.setattr(service, '_stop_cleanup', threading.Event())+ monkeypatch.setattr(module.threading, 'Thread', constructor)+ service.start_cleanup()+ service.start_cleanup()+ constructor.assert_called_once()+ thread.start.assert_called_once()+++def test_heartbeat_runtime_captures_the_serving_app(monkeypatch):+ from app.services.agent_registry import agent_registry+ start = Mock()+ monkeypatch.setattr(agent_registry, '_start_heartbeat_checker', start)+ monkeypatch.setattr(agent_registry, '_app', None)+ server = object()+ agent_registry.start(server)+ assert agent_registry._app is server+ start.assert_called_once_with()++def test_bootstrap_is_an_assembly_layer_not_a_service_dependency():root = Path(__file__).parents[1] / 'app'for folder in ('api', 'services', 'models', 'jobs'):diff --git a/backend/tests/test_no_background_threads.py b/backend/tests/test_no_background_threads.pyindex 158f0db7..f7f89065 100644--- a/backend/tests/test_no_background_threads.py+++ b/backend/tests/test_no_background_threads.py@@ -13,6 +13,8 @@ the queue-bus consumers) or started only by an explicit runtime trigger"""import threading+import pytest+def _thread_ids():return {t.ident for t in threading.enumerate()}@@ -48,3 +50,44 @@ def test_create_app_testing_spawns_no_background_threads():finally:db.session.remove()db.drop_all()++[email protected]('failed_phase', [None, 'persistence', 'plugins'])+def test_factory_phase_order_and_context(monkeypatch, failed_phase):+ import app as application+ from flask import has_app_context+ from app.bootstrap import configuration, persistence, plugins, http, runtime+ import app.sockets+ import app.agent_gateway+ import app.core_blueprints+ from app.services import recycle_bin_service, restore_point_adapters++ calls = []+ def phase(name, context=False):+ def run(*args):+ assert has_app_context() is context+ calls.append(name)+ if name == failed_phase:+ raise RuntimeError('startup failed')+ return run++ monkeypatch.setattr(configuration, 'configure_application', phase('configuration'))+ monkeypatch.setattr(app.sockets, 'init_socketio', phase('socket'))+ monkeypatch.setattr(app.agent_gateway, 'init_agent_gateway', phase('gateway'))+ monkeypatch.setattr(app.core_blueprints, 'register_core_blueprints', phase('routes'))+ monkeypatch.setattr(recycle_bin_service, 'register_builtin_types', phase('recycle'))+ monkeypatch.setattr(restore_point_adapters, 'register_builtin_restore_point_adapters', phase('restore'))+ monkeypatch.setattr(persistence, 'prepare_persistence', phase('persistence', True))+ monkeypatch.setattr(plugins, 'load_extensions', phase('plugins', True))+ monkeypatch.setattr(runtime, 'start_runtime', phase('runtime', True))+ monkeypatch.setattr(http, 'register_http_handlers', phase('http'))+ monkeypatch.setattr(application, 'socketio', application.socketio)+ expected = ['configuration', 'socket', 'gateway', 'routes', 'recycle',+ 'restore', 'persistence', 'plugins', 'runtime', 'http']+ if failed_phase:+ with pytest.raises(RuntimeError, match='startup failed'):+ application.create_app('testing')+ assert calls == expected[:expected.index(failed_phase) + 1]+ else:+ application.create_app('testing')+ assert calls == expecteddiff --git a/backend/tests/test_worker_processes.py b/backend/tests/test_worker_processes.pyindex 62d5950c..8280e202 100644--- a/backend/tests/test_worker_processes.py+++ b/backend/tests/test_worker_processes.py@@ -96,11 +96,16 @@ class TestDeploy:assert result['started'] == [] and set(result['failed']) == {'worker', 'scheduler'}-def test_build_pack_containers_are_listed_web_first(app, fake_subprocess):[email protected]('compose_command', [None, ['docker', 'compose'], ['docker-compose']])+def test_build_pack_containers_are_listed_web_first(app, fake_subprocess, monkeypatch, compose_command):+ # Prior tests can cache either Compose flavor. Both must yield the same+ # build-pack fallback; keep the fake transport independent of test order.+ monkeypatch.setattr(DockerService, '_compose_cmd', compose_command)site = make_application(db, name='shop', buildpack_type='python', root_path='/nonexistent')rows = [{'ID': 'w1', 'Names': f'serverkit-app-{site.id}-worker', 'State': 'running'},{'ID': 'm1', 'Names': f'serverkit-app-{site.id}', 'State': 'running'}]fake_subprocess.script(['docker', 'compose'], stdout='')+ fake_subprocess.script(['docker-compose'], stdout='')fake_subprocess.script(['docker', 'ps'], stdout='\n'.join(json.dumps(r) for r in rows))listed = DockerService.get_all_app_containers(site)assert [(c['id'], c['service']) for c in listed] == [('m1', 'web'), ('w1', 'worker')]diff --git a/docs/CORE_BOUNDARIES.md b/docs/CORE_BOUNDARIES.mdindex 080a22d0..57f587ba 100644--- a/docs/CORE_BOUNDARIES.md+++ b/docs/CORE_BOUNDARIES.md@@ -23,14 +23,18 @@ context. Database preparation precedes extension queries; interrupted-jobrecovery precedes consumers; job handlers precede the job consumer. One-shotFlask commands and `SERVERKIT_SKIP_BACKGROUND` suppress runtime startup.The existing individual services retain their testing and singleton guards.+Agent heartbeat, nonce retention and anomaly retention are explicitly started+by `bootstrap/agents.py`; importing services or binding the gateway does not+launch those threads. The heartbeat runtime receives the serving Flask app.Bootstrap may depend on services, models, middleware and jobs. Those layersmust not import bootstrap. A feature exposes a registration/initializationfunction; its appropriate bootstrap phase invokes it. Existing migrationpolicy and fail-soft extension behavior are preserved by this split.-`backend/tests/test_bootstrap_boundaries.py` enforces dependency direction,-factory composition, startup order, context, and CLI suppression. The core+`backend/tests/test_bootstrap_boundaries.py` and `test_no_background_threads.py`+enforce dependency direction, factory composition, startup order, context,+worker lifecycle, and CLI suppression. The coreblueprint registry and API-error tests verify the assembled application.## File Manager@@ -77,6 +81,7 @@ adapter but does not issue API calls or await requests.target switching, late results, editing, confirmations and uploads.- `npm run build`: verify the complete production import graph.- `python -m pytest tests/test_bootstrap_boundaries.py+ tests/test_no_background_threads.pytests/test_core_blueprint_registry.py tests/test_cli_skips_background.pytests/test_api_error_shape.py` in `backend`: focused startup coverage.- Run the full backend suite for application assembly changes.diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.mdindex 85d2a556..1709215c 100644--- a/docs/MIGRATION_INVENTORY.md+++ b/docs/MIGRATION_INVENTORY.md@@ -19,8 +19,8 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 848 | 850 | migrate when touched; new endpoints raise || Raw subprocess calls outside the runners | app/utils/system.py runners | 23 | 23 | migrate when touched || Controller-boundary violations (routes doing service work) | service layer extraction | 477 | 477 | migrate when touched (first-wave ratchet) |-| raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 395 | 398 | migrate when touched |-| per-page toast.error extractions in pages/ | E1: query-layer error presentation | 199 | 206 | migrate when touched |+| raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 374 | 398 | migrate when touched |+| per-page toast.error extractions in pages/ | E1: query-layer error presentation | 191 | 206 | migrate when touched || hand-rolled form-group blocks | F2: FormField/useForm | 314 | 321 | migrate when touched || unencoded ?k=${v} query interpolations in services/api | C4: buildQuery/encoding template | 0 | 0 | INVARIANT at 0 || raw setInterval pollers | E2: usePolling/refetchInterval | 7 | 7 | DELIBERATE RESIDUE: clock ticks, socket-fallback hooks, and sibling-repo extension timers - each listed per file |diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjsindex 2a5c325c..1bb3ca42 100644--- a/frontend/scripts/check-frontend-boundaries.mjs+++ b/frontend/scripts/check-frontend-boundaries.mjs@@ -9,9 +9,12 @@import { existsSync, readFileSync, readdirSync } from 'node:fs';import { dirname, extname, join, relative, resolve } from 'node:path';import { fileURLToPath } from 'node:url';-import { checkFileManagerBoundaries } from './check-file-manager-boundaries.mjs';--checkFileManagerBoundaries();+// Inventory is also consumed by backend-only CI without npm dependencies.+// The AST architecture guard runs with the normal frontend lint toolchain.+if (!process.argv.includes('--inventory')) {+ const { checkFileManagerBoundaries } = await import('./check-file-manager-boundaries.mjs');+ checkFileManagerBoundaries();+}const here = dirname(fileURLToPath(import.meta.url));const root = resolve(here, '..');@@ -122,7 +125,8 @@ function walk(dir) {});}-const files = walk(src).filter((path) => ['.js', '.jsx'].includes(extname(path)));+const files = walk(src).filter((path) => ['.js', '.jsx'].includes(extname(path))+ && !relative(src, path).replaceAll('\\', '/').split('/').includes('__tests__'));const failures = [];const seenClipboard = new Set();const seenPollers = new Set();diff --git a/frontend/scripts/file-manager-browser.mjs b/frontend/scripts/file-manager-browser.mjsindex f46c1800..ab58062b 100644--- a/frontend/scripts/file-manager-browser.mjs+++ b/frontend/scripts/file-manager-browser.mjs@@ -339,6 +339,21 @@ try {assert.equal(await deepLink.getByText('projects', { exact: true }).count(), 0);assert.equal(await deepLink.getByTitle('Back', { exact: true }).isDisabled(), true);console.log('PASS initial deep links retain their directory and history');++ const clearing = await browser.newPage();+ await clearing.goto(`http://127.0.0.1:${server.httpServer.address().port}/fm-check`);+ await clearing.getByText('projects', { exact: true }).first().waitFor();+ await clearing.getByPlaceholder('Search files…').fill('draft query');+ await clearing.getByText('projects', { exact: true }).first().dblclick();+ await clearing.waitForFunction(() => window.pending.some(x => x.path === '/home/projects'));+ await clearing.locator('.search-field-clear').click();+ assert.equal(await clearing.locator('.file-manager-main').getByText('projects', { exact: true }).count(), 0,+ 'clearing a query must not expose the previous directory listing while browsing');+ await clearing.evaluate(() => {+ while (window.pending.some(x => x.path === '/home/projects')) window.release('/home/projects');+ });+ await clearing.getByText('inside-projects.txt', { exact: true }).waitFor();+ console.log('PASS clearing a query during navigation preserves the pending directory load');} finally {await browser?.close();await server.close();diff --git a/frontend/src/components/file-manager/hooks/useDirectoryBrowser.js b/frontend/src/components/file-manager/hooks/useDirectoryBrowser.jsindex 755d2995..eb5743e1 100644--- a/frontend/src/components/file-manager/hooks/useDirectoryBrowser.js+++ b/frontend/src/components/file-manager/hooks/useDirectoryBrowser.js@@ -183,7 +183,9 @@ export default function useDirectoryBrowser({loadSeqRef.current++;setSearchResults(null);setSearchQuery('');- setLoading(false);+ // A directory browse may also be pending. Restore the current listing+ // instead of revealing entries from the previously visited folder.+ loadDirectory(currentPath);};const handleSearch = async () => {if (remoteGuard('search')) {