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.

feat(realtime): generalized run envelope — one stream door for every run kind (plan 77 E1)

Juan Denisb0589e95db0e
diff --git a/backend/app/api/runs.py b/backend/app/api/runs.py
new file mode 100644
index 00000000..0416e3c3
--- /dev/null
+++ b/backend/app/api/runs.py
@@ -0,0 +1,25 @@
+"""Run envelope REST twin (plan 77 E1).
+
+The polling counterpart of the `run_log` / `run_status` socket events: any
+run kind's persisted lines, resumable via ?after_id, so a client that missed
+socket frames (or has sockets disabled) can always catch up. The deploy kind
+keeps its richer legacy endpoint (/api/v1/deployment-jobs/<id>/logs) — this
+one serves every kind stored in run_log_entries.
+"""
+from flask import Blueprint, jsonify, request
+from flask_jwt_extended import jwt_required
+
+from app.models.run_log import RunLogEntry
+
+runs_bp = Blueprint('runs', __name__)
+
+
+@runs_bp.route('/<run_kind>/<run_id>/logs', methods=['GET'])
+@jwt_required()
+def get_run_logs(run_kind, run_id):
+ after_id = request.args.get('after_id', type=int)
+ query = RunLogEntry.query.filter_by(run_kind=run_kind, run_id=str(run_id))
+ if after_id:
+ query = query.filter(RunLogEntry.id > after_id)
+ rows = query.order_by(RunLogEntry.id.asc()).limit(2000).all()
+ return jsonify({'logs': [row.to_dict() for row in rows]}), 200
diff --git a/backend/app/core_blueprints.py b/backend/app/core_blueprints.py
index fdc52ec0..31d2e603 100644
--- a/backend/app/core_blueprints.py
+++ b/backend/app/core_blueprints.py
@@ -117,6 +117,7 @@ CORE_BLUEPRINTS: tuple[BlueprintSpec, ...] = (
'/api/v1/deployments/jobs',
name='deployment_jobs_unified',
),
+ BlueprintSpec('app.api.runs', 'runs_bp', '/api/v1/runs'),
BlueprintSpec('app.api.templates', 'templates_bp', '/api/v1/templates'),
BlueprintSpec('app.api.files', 'files_bp', '/api/v1/files'),
BlueprintSpec('app.api.firewall', 'firewall_bp', '/api/v1/firewall'),
diff --git a/backend/app/jobs/consumer.py b/backend/app/jobs/consumer.py
index 70061482..bcccc5e9 100644
--- a/backend/app/jobs/consumer.py
+++ b/backend/app/jobs/consumer.py
@@ -104,6 +104,16 @@ class JobConsumer:
job.queue_message_id = message['id']
db.session.commit()
+ # Live run envelope (plan 77 E1): unified jobs stream through the same
+ # RunLogStream seam as deploys — run_log/run_status into run_job_<id>,
+ # resumable over GET /api/v1/runs/job/<id>/logs?after_id. Handlers can
+ # log through stream_for(job) themselves; these frames bracket the run.
+ from app.services.run_log_service import stream_for
+ stream = stream_for(job)
+ stream.log('info', f'Job started: {job.kind} (attempt {job.attempts + 1})')
+ stream.flush()
+ stream.emit_status()
+
try:
result = handler(job)
job = Job.query.get(job_id) # handler may have committed/expired the row
@@ -113,6 +123,8 @@ class JobConsumer:
job.error_message = None
db.session.commit()
QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ stream.log('info', f'Job succeeded: {job.kind}')
+ stream.close(Job.STATUS_SUCCEEDED)
self._emit(job, 'job.succeeded')
except Exception as e:
logger.error(f'Job {job_id} ({job.kind}) failed: {e}')
@@ -120,7 +132,9 @@ class JobConsumer:
db.session.rollback()
except Exception:
pass
+ stream.log('error', f'Job failed: {e}')
self._fail(job_id, message, str(e))
+ stream.close('failed')
def _fail(self, job_id, message, error):
outcome = None
diff --git a/backend/app/jobs/models.py b/backend/app/jobs/models.py
index d310a2e5..9a7ac0c7 100644
--- a/backend/app/jobs/models.py
+++ b/backend/app/jobs/models.py
@@ -21,6 +21,9 @@ from app import db
class Job(db.Model):
__tablename__ = 'jobs'
+ # Run envelope kind (plan 77 E1): rooms/events key on (run_kind, id).
+ __run_kind__ = 'job'
+
STATUS_PENDING = 'pending'
STATUS_RUNNING = 'running'
STATUS_SUCCEEDED = 'succeeded'
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 6b3b31b1..e7c919a2 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -22,6 +22,7 @@ from app.models.workflow import Workflow, WorkflowExecution, WorkflowLog
from app.models.webhook import GitWebhook, WebhookLog, GitDeployment
from app.models.server import Server, ServerGroup, ServerMetrics, ServerCommand, AgentSession, AgentVersion, AgentRollout
from app.models.server_onboarding_log import ServerOnboardingLog
+from app.models.run_log import RunLogEntry
from app.models.security_alert import SecurityAlert
from app.models.wordpress_site import WordPressSite, DatabaseSnapshot, SyncJob, WordPressVulnerability
from app.models.wordpress_custom_plugin import WordPressCustomPlugin, WordPressSitePlugin
diff --git a/backend/app/models/deployment_job.py b/backend/app/models/deployment_job.py
index 6577a995..2aab5b6d 100644
--- a/backend/app/models/deployment_job.py
+++ b/backend/app/models/deployment_job.py
@@ -16,6 +16,9 @@ class DeploymentJob(RunLifecycleMixin, JsonColumnMixin, db.Model):
__tablename__ = 'deployment_jobs'
+ # Run envelope kind (plan 77 E1): rooms/events key on (run_kind, id).
+ __run_kind__ = 'deploy'
+
# Stored spelling predates the canonical vocabulary (plan 77 D1);
# override until this domain's data migration rewrites 'succeeded'.
__status_success__ = 'succeeded'
diff --git a/backend/app/models/run_log.py b/backend/app/models/run_log.py
new file mode 100644
index 00000000..f841a23b
--- /dev/null
+++ b/backend/app/models/run_log.py
@@ -0,0 +1,41 @@
+"""Generic run-scoped log rows (plan 77 E1).
+
+``DeploymentJobLog`` predates this table and stays the store for the deploy
+kind; every OTHER run kind (unified jobs, sandbox runs, site imports,
+backups) persists its stream lines here, keyed by ``(run_kind, run_id)`` —
+the same key the ``run_<kind>_<id>`` socket room and the
+``GET /api/v1/runs/<kind>/<id>/logs?after_id`` polling twin use, so a client
+can always resync after a dropped socket.
+"""
+from datetime import datetime
+
+from app import db
+
+
+class RunLogEntry(db.Model):
+ __tablename__ = 'run_log_entries'
+
+ id = db.Column(db.Integer, primary_key=True)
+ run_kind = db.Column(db.String(40), nullable=False)
+ run_id = db.Column(db.String(64), nullable=False)
+ step_index = db.Column(db.Integer, nullable=True)
+ level = db.Column(db.String(10), default='info', nullable=False)
+ message = db.Column(db.Text, nullable=False, default='')
+ data = db.Column(db.Text, nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+
+ __table_args__ = (
+ # The one access pattern: a run's lines in id order, optionally after a
+ # known id (the resync cursor).
+ db.Index('ix_run_log_entries_kind_run_id', 'run_kind', 'run_id', 'id'),
+ )
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'step_index': self.step_index,
+ 'level': self.level,
+ 'message': self.message,
+ 'data': self.data,
+ 'ts': self.created_at.isoformat() if self.created_at else None,
+ }
diff --git a/backend/app/services/run_log_service.py b/backend/app/services/run_log_service.py
index 640ee26c..435de995 100644
--- a/backend/app/services/run_log_service.py
+++ b/backend/app/services/run_log_service.py
@@ -106,27 +106,41 @@ def match_hint(tail_text: str) -> Optional[str]:
return None
-def _default_emit_log(job_id: str, lines: List[dict]) -> None:
+def _make_default_emit_log(run_kind: str) -> Callable:
"""Lazy default emitter — resolves the socket helper at call time so this
module never imports sockets eagerly and stays safe when sockets aren't
- wired (tests, CLI)."""
- try:
- from app.sockets import emit_deploy_log
- emit_deploy_log(job_id, lines)
- except Exception:
- pass
+ wired (tests, CLI). Emits the generalized run envelope; the deploy kind
+ dual-emits the legacy deploy_log inside emit_run_log."""
+ def _emit(run_id, lines: List[dict]) -> None:
+ try:
+ from app.sockets import emit_run_log
+ emit_run_log(run_kind, run_id, lines)
+ except Exception:
+ pass
+ return _emit
-def _default_emit_status(job_id: str, status: dict) -> None:
- try:
- from app.sockets import emit_deploy_status
- emit_deploy_status(job_id, status)
- except Exception:
- pass
+def _make_default_emit_status(run_kind: str) -> Callable:
+ def _emit(run_id, status: dict) -> None:
+ try:
+ from app.sockets import emit_run_status
+ emit_run_status(run_kind, run_id, status)
+ except Exception:
+ pass
+ return _emit
class RunLogStream:
- """Batched, crash-proof log writer for one DeploymentJob."""
+ """Batched, crash-proof log writer for one run.
+
+ Generalized (plan 77 E1) over any model implementing the small RunLike
+ protocol: an ``id``, a ``__run_kind__`` class attribute, a ``to_dict()``
+ for status emits, and — optionally — ``get_result``/``set_result`` (for
+ close-time enrichment) and ``current_step``/``current_step_name`` (for
+ step tracking). DeploymentJob keeps its dedicated log table; every other
+ kind persists to the generic ``run_log_entries`` table under the same
+ ``(run_kind, run_id)`` key the socket room and the REST resync twin use.
+ """
FLUSH_LINES = 50
FLUSH_INTERVAL = 0.3 # seconds
@@ -141,13 +155,15 @@ class RunLogStream:
clock: Callable[[], float] = time.monotonic,
):
self.job = job
+ self.run_kind = getattr(job, '__run_kind__', 'deploy')
+ self._is_deploy = isinstance(job, DeploymentJob)
self._buffer: List[dict] = []
self._clock = clock
self._last_flush = clock()
self._tail = deque(maxlen=self.TAIL_SIZE)
self._cap_hit = False
- self._emit_log = emit_log or _default_emit_log
- self._emit_status = emit_status or _default_emit_status
+ self._emit_log = emit_log or _make_default_emit_log(self.run_kind)
+ self._emit_status = emit_status or _make_default_emit_status(self.run_kind)
# Per-step timing: index -> {'name', 'started'}; finalized into a list.
self._step_started_at: Optional[float] = None
@@ -155,17 +171,44 @@ class RunLogStream:
self._step_started_name: Optional[str] = None
self._step_timings: List[dict] = []
- # How many rows already exist for this job (retries make fresh jobs, but
- # a reconciled/resumed job could carry rows) — the cap is per job.
+ # How many rows already exist for this run (retries make fresh runs, but
+ # a reconciled/resumed one could carry rows) — the cap is per run.
try:
- self._rows_written = DeploymentJobLog.query.filter_by(job_id=job.id).count()
+ self._rows_written = self._row_query().count()
except Exception:
self._rows_written = 0
@classmethod
- def for_job(cls, job: DeploymentJob, **kwargs) -> 'RunLogStream':
+ def for_job(cls, job, **kwargs) -> 'RunLogStream':
return cls(job, **kwargs)
+ # ------------------------------------------------------------- storage
+ def _row_query(self):
+ if self._is_deploy:
+ return DeploymentJobLog.query.filter_by(job_id=self.job.id)
+ from app.models.run_log import RunLogEntry
+ return RunLogEntry.query.filter_by(
+ run_kind=self.run_kind, run_id=str(self.job.id))
+
+ def _new_row(self, row: dict):
+ if self._is_deploy:
+ return DeploymentJobLog(
+ job_id=self.job.id,
+ step_index=row['step_index'],
+ level=row['level'],
+ message=row['message'],
+ data=row['data'],
+ )
+ from app.models.run_log import RunLogEntry
+ return RunLogEntry(
+ run_kind=self.run_kind,
+ run_id=str(self.job.id),
+ step_index=row['step_index'],
+ level=row['level'],
+ message=row['message'],
+ data=row['data'],
+ )
+
# ------------------------------------------------------------------ log
def log(self, level: str, message: str, step_index: Optional[int] = None,
data: Any = None) -> None:
@@ -231,8 +274,9 @@ class RunLogStream:
self._step_started_index = index
self._step_started_name = name
- self.job.current_step = index
- self.job.current_step_name = name
+ if hasattr(self.job, 'current_step'):
+ self.job.current_step = index
+ self.job.current_step_name = name
db.session.commit()
self._emit_status_safe()
except Exception:
@@ -250,17 +294,18 @@ class RunLogStream:
self._flush()
self._finalize_current_step()
- result = self.job.get_result() or {}
- if self._step_timings:
- result['step_timings'] = self._step_timings
- if status == 'failed':
- tail = list(self._tail)
- result['failure_tail'] = tail
- hint = match_hint('\n'.join(tail))
- if hint:
- result['hint'] = hint
- self.job.set_result(result)
- db.session.commit()
+ if hasattr(self.job, 'get_result') and hasattr(self.job, 'set_result'):
+ result = self.job.get_result() or {}
+ if self._step_timings:
+ result['step_timings'] = self._step_timings
+ if status == 'failed':
+ tail = list(self._tail)
+ result['failure_tail'] = tail
+ hint = match_hint('\n'.join(tail))
+ if hint:
+ result['hint'] = hint
+ self.job.set_result(result)
+ db.session.commit()
except Exception:
try:
db.session.rollback()
@@ -278,16 +323,7 @@ class RunLogStream:
pending = self._buffer
self._buffer = []
try:
- entries = [
- DeploymentJobLog(
- job_id=self.job.id,
- step_index=row['step_index'],
- level=row['level'],
- message=row['message'],
- data=row['data'],
- )
- for row in pending
- ]
+ entries = [self._new_row(row) for row in pending]
db.session.add_all(entries)
db.session.commit()
self._rows_written += len(entries)
@@ -315,7 +351,7 @@ class RunLogStream:
try:
from app.services.telemetry_service import TelemetryService
TelemetryService.emit(
- source='deployment',
+ source='deployment' if self._is_deploy else 'runs',
event_type='deployment.log_flush_failed',
message='Deploy log flush failed; dropped a buffered batch',
severity='warning',
@@ -348,6 +384,11 @@ class RunLogStream:
self._step_started_at = None
self._step_started_name = None
+ def emit_status(self) -> None:
+ """Public status emit for transitions that happen outside close()
+ (e.g. the job consumer announcing 'running')."""
+ self._emit_status_safe()
+
def _emit_status_safe(self) -> None:
try:
self._emit_status(self.job.id, self.job.to_dict())
@@ -370,7 +411,7 @@ def _trim_data(data: Any) -> Any:
_STREAM_ATTR = '_run_log_stream'
-def stream_for(job: DeploymentJob) -> RunLogStream:
+def stream_for(job) -> RunLogStream:
"""Return the one stream for *job*, creating it on first use.
Used where the logging and the terminal ``close()`` sit in different places:
@@ -390,7 +431,7 @@ def stream_for(job: DeploymentJob) -> RunLogStream:
return stream
-def append_log(job: DeploymentJob, level: str, message: str, data: Any = None,
+def append_log(job, level: str, message: str, data: Any = None,
step_index: Optional[int] = None) -> None:
"""Immediate, persisted single log line for fire-and-forget annotations
(e.g. post-install notes) where no long-lived stream is open. Flushes at
diff --git a/backend/app/sockets.py b/backend/app/sockets.py
index 838fcfed..8a068540 100644
--- a/backend/app/sockets.py
+++ b/backend/app/sockets.py
@@ -451,6 +451,52 @@ def emit_deploy_status(job_id: str, status: dict):
}, room=rooms.deploy_room(job_id))
+# ==================== GENERALIZED RUN ENVELOPE (plan 77 E1) ====================
+#
+# One event pair for every run kind, keyed by (run_kind, run_id) in the room
+# run_<kind>_<id>. The deploy kind dual-emits the legacy deploy_log /
+# deploy_status pair above during the migration window so existing Deploy
+# Console listeners keep working.
+
+def emit_run_log(run_kind: str, run_id, lines: list):
+ """Emit a batch of persisted run log lines to the run's envelope room."""
+ socketio.emit('run_log', {
+ 'run_kind': run_kind,
+ 'run_id': run_id,
+ 'lines': lines,
+ }, room=rooms.run_room(run_kind, run_id))
+ if run_kind == 'deploy':
+ emit_deploy_log(run_id, lines)
+
+
+def emit_run_status(run_kind: str, run_id, status: dict):
+ """Emit a run's status summary to the run's envelope room."""
+ socketio.emit('run_status', {
+ 'run_kind': run_kind,
+ 'run_id': run_id,
+ 'status': status,
+ }, room=rooms.run_room(run_kind, run_id))
+ if run_kind == 'deploy':
+ emit_deploy_status(run_id, status)
+
+
+def _run_channel_room(data):
+ run_kind = data.get('run_kind')
+ run_id = data.get('run_id')
+ if not run_kind or run_id in (None, ''):
+ raise ChannelError('run_kind and run_id required')
+ return rooms.run_room(run_kind, run_id)
+
+
+# Auth mirrors the deploy channel: any authenticated user may watch — run ids
+# are unguessable and the REST twin exposes the same data the same way.
+register_channel(
+ 'run',
+ room_fn=_run_channel_room,
+ ack=lambda data: {'run_kind': data.get('run_kind'), 'run_id': data.get('run_id')},
+)
+
+
# ==================== CONTAINER LOG STREAMING ====================
@socketio.on('subscribe_container_logs')
diff --git a/backend/migrations/versions/087_run_log_entries.py b/backend/migrations/versions/087_run_log_entries.py
new file mode 100644
index 00000000..a4abca29
--- /dev/null
+++ b/backend/migrations/versions/087_run_log_entries.py
@@ -0,0 +1,49 @@
+"""Generic run-scoped log rows (plan 77 E1): new `run_log_entries` table.
+
+DeploymentJobLog stays the store for the deploy kind; every other run kind
+(unified jobs, sandbox runs, site imports, backups) persists its stream lines
+here, keyed by (run_kind, run_id) — the same key as the run_<kind>_<id>
+socket room and the /api/v1/runs polling twin.
+
+Revision ID: 087_run_log_entries
+Revises: 086_host_snapshots
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = '087_run_log_entries'
+down_revision = '086_host_snapshots'
+branch_labels = None
+depends_on = None
+
+
+def _has_table(name):
+ bind = op.get_bind()
+ return name in sa.inspect(bind).get_table_names()
+
+
+def upgrade():
+ if _has_table('run_log_entries'):
+ return
+ op.create_table(
+ 'run_log_entries',
+ sa.Column('id', sa.Integer(), primary_key=True),
+ sa.Column('run_kind', sa.String(length=40), nullable=False),
+ sa.Column('run_id', sa.String(length=64), nullable=False),
+ sa.Column('step_index', sa.Integer(), nullable=True),
+ sa.Column('level', sa.String(length=10), nullable=False, server_default='info'),
+ sa.Column('message', sa.Text(), nullable=False, server_default=''),
+ sa.Column('data', sa.Text(), nullable=True),
+ sa.Column('created_at', sa.DateTime(), nullable=True),
+ )
+ op.create_index(
+ 'ix_run_log_entries_kind_run_id', 'run_log_entries',
+ ['run_kind', 'run_id', 'id'],
+ )
+
+
+def downgrade():
+ if not _has_table('run_log_entries'):
+ return
+ op.drop_index('ix_run_log_entries_kind_run_id', table_name='run_log_entries')
+ op.drop_table('run_log_entries')
diff --git a/backend/tests/test_run_envelope.py b/backend/tests/test_run_envelope.py
new file mode 100644
index 00000000..05a69b42
--- /dev/null
+++ b/backend/tests/test_run_envelope.py
@@ -0,0 +1,142 @@
+"""Plan 77 E1 gate — the generalized run envelope.
+
+Contract: a stream line for any RunLike is (1) persisted in run_log_entries
+under (run_kind, run_id), (2) emitted as a run_log batch carrying the real DB
+ids, and (3) recoverable over GET /api/v1/runs/<kind>/<id>/logs?after_id —
+so a client that missed socket frames can always resync.
+"""
+import pytest
+
+from app import db
+from app.jobs.models import Job
+from app.models.run_log import RunLogEntry
+from app.services.run_log_service import RunLogStream
+
+
+class _Emitter:
+ def __init__(self):
+ self.log_calls = []
+ self.status_calls = []
+
+ def emit_log(self, run_id, lines):
+ self.log_calls.append((run_id, lines))
+
+ def emit_status(self, run_id, status):
+ self.status_calls.append((run_id, status))
+
+
+def _make_job(kind='envelope-test'):
+ job = Job(kind=kind)
+ db.session.add(job)
+ db.session.commit()
+ return job
+
+
+def test_emit_persist_and_after_id_resync(app, client, auth_headers):
+ job = _make_job()
+ emitter = _Emitter()
+ stream = RunLogStream.for_job(job, emit_log=emitter.emit_log,
+ emit_status=emitter.emit_status)
+ assert stream.run_kind == 'job'
+
+ stream.log('info', 'first line')
+ stream.flush()
+ stream.log('warn', 'second line')
+ stream.flush()
+
+ rows = (RunLogEntry.query
+ .filter_by(run_kind='job', run_id=str(job.id))
+ .order_by(RunLogEntry.id).all())
+ assert [r.message for r in rows] == ['first line', 'second line']
+
+ # the emitted batches carry the REAL persisted ids (dedupe/resync anchor)
+ emitted_ids = [line['id'] for _, lines in emitter.log_calls for line in lines]
+ assert emitted_ids == [r.id for r in rows]
+
+ # REST resync twin
+ resp = client.get(f'/api/v1/runs/job/{job.id}/logs', headers=auth_headers)
+ assert resp.status_code == 200
+ logs = resp.get_json()['logs']
+ assert [l['message'] for l in logs] == ['first line', 'second line']
+
+ resp = client.get(f'/api/v1/runs/job/{job.id}/logs?after_id={rows[0].id}',
+ headers=auth_headers)
+ assert [l['message'] for l in resp.get_json()['logs']] == ['second line']
+
+
+def test_runs_endpoint_requires_auth(app, client):
+ resp = client.get('/api/v1/runs/job/nope/logs')
+ assert resp.status_code == 401
+
+
+def test_close_emits_terminal_status(app):
+ job = _make_job()
+ emitter = _Emitter()
+ stream = RunLogStream.for_job(job, emit_log=emitter.emit_log,
+ emit_status=emitter.emit_status)
+ stream.log('info', 'line')
+ stream.close('succeeded')
+ assert emitter.status_calls, 'close() must emit a terminal status'
+
+
+def test_default_emitters_use_run_envelope(app, monkeypatch):
+ calls = []
+ import app.sockets as sk
+ monkeypatch.setattr(sk, 'emit_run_log',
+ lambda kind, rid, lines: calls.append((kind, rid, len(lines))))
+ job = _make_job()
+ stream = RunLogStream.for_job(job)
+ stream.log('info', 'hello')
+ stream.flush()
+ assert calls and calls[0][0] == 'job' and calls[0][1] == job.id
+
+
+def test_deploy_kind_dual_emits_legacy_events(app, monkeypatch):
+ import app.sockets as sk
+ events = []
+ monkeypatch.setattr(sk.socketio, 'emit',
+ lambda name, payload, room=None: events.append((name, room)))
+ sk.emit_run_log('deploy', 'j1', [{'id': 1}])
+ assert ('run_log', 'run_deploy_j1') in events
+ assert ('deploy_log', 'deploy_j1') in events
+
+ events.clear()
+ sk.emit_run_status('deploy', 'j1', {'status': 'running'})
+ assert ('run_status', 'run_deploy_j1') in events
+ assert ('deploy_status', 'deploy_j1') in events
+
+
+def test_non_deploy_kind_does_not_dual_emit(app, monkeypatch):
+ import app.sockets as sk
+ events = []
+ monkeypatch.setattr(sk.socketio, 'emit',
+ lambda name, payload, room=None: events.append((name, room)))
+ sk.emit_run_log('job', 'x', [])
+ assert events == [('run_log', 'run_job_x')]
+
+
+def test_job_consumer_streams_the_run(app, monkeypatch):
+ """A unified job processed by the consumer produces persisted run frames —
+ Jobs finally have a live channel with a polling twin."""
+ from app.jobs import registry as jobs_registry
+ from app.jobs.consumer import JobConsumer
+ from app.queue_bus.service import QueueBusService
+
+ monkeypatch.setattr(QueueBusService, 'complete',
+ staticmethod(lambda *a, **k: None))
+
+ calls = []
+ jobs_registry.register('envelope-proof',
+ lambda job: calls.append(job.id) or {'ok': True},
+ replace=True)
+
+ job = _make_job(kind='envelope-proof')
+ consumer = JobConsumer(app=app)
+ consumer.process_message({'id': 'm1', 'payload': {'job_id': job.id}, 'attempts': 0})
+
+ assert calls == [job.id]
+ assert Job.query.get(job.id).status == Job.STATUS_SUCCEEDED
+ rows = RunLogEntry.query.filter_by(run_kind='job', run_id=str(job.id)).all()
+ messages = [r.message for r in rows]
+ assert any('Job started' in m for m in messages)
+ assert any('Job succeeded' in m for m in messages)
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
index 58b6cfc4..871f757b 100644
--- a/docs/MIGRATION_INVENTORY.md
+++ b/docs/MIGRATION_INVENTORY.md
@@ -13,7 +13,7 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.
| Concern | Door | Remaining | Ceiling | Policy |
|---|---|---:|---:|---|
| Identity lookups outside rbac.get_current_user() | rbac.get_current_user() | 69 | 69 | JWT-only routes; the API-key-capable population is held at 0 by a companion assertion |
-| Routes on bare @jwt_required() | auth_required() / role decorators | 605 | 605 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
+| Routes on bare @jwt_required() | auth_required() / role decorators | 606 | 605 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
| HTTP statuses chosen by sniffing error text | typed errors from app.exceptions | 0 | 0 | INVARIANT at 0 - migration completed 2026-08-19 |
| API crashes swallowed without recording | app.error_reporting | 0 | 0 | INVARIANT at 0 |
| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 1159 | 1159 | migrate when touched; new endpoints raise |