Skip to content

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.

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.py
new file mode 100644
index 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.py
index 915bc6da..d03908a4 100644
--- a/backend/app/bootstrap/runtime.py
+++ b/backend/app/bootstrap/runtime.py
@@ -29,6 +29,9 @@ def start_runtime(app):
import logging
logging.getLogger(__name__).exception('Interrupted-job recovery failed')
+ from app.bootstrap.agents import start_agent_runtime
+ start_agent_runtime(app)
+
# Start metrics history collection in background
from app.services.metrics_history_service import MetricsHistoryService
if not MetricsHistoryService.is_running():
diff --git a/backend/app/jobs/thread_ownership.py b/backend/app/jobs/thread_ownership.py
index 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.py
index 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 = app
self._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.py
index 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 thread
self._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=True
diff --git a/backend/app/services/nonce_service.py b/backend/app/services/nonce_service.py
index 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 thread
self._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=True
diff --git a/backend/tests/test_bootstrap_boundaries.py b/backend/tests/test_bootstrap_boundaries.py
index 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.py
index 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 == expected
diff --git a/backend/tests/test_worker_processes.py b/backend/tests/test_worker_processes.py
index 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.md
index 080a22d0..57f587ba 100644
--- a/docs/CORE_BOUNDARIES.md
+++ b/docs/CORE_BOUNDARIES.md
@@ -23,14 +23,18 @@ context. Database preparation precedes extension queries; interrupted-job
recovery precedes consumers; job handlers precede the job consumer. One-shot
Flask 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 layers
must not import bootstrap. A feature exposes a registration/initialization
function; its appropriate bootstrap phase invokes it. Existing migration
policy 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 core
blueprint 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.py
tests/test_core_blueprint_registry.py tests/test_cli_skips_background.py
tests/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.md
index 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.mjs
index 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.mjs
index 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.js
index 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')) {