portal-mojo 0.2.4 → 0.2.5

package/docs/README.md

@@ -19,12 +19,14 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |
 | [admin-metrics-explorer.md](admin-metrics-explorer.md) | Read-only recorded-metrics discovery, full-slug adapters, KPI/fan-out/scalar contracts, and cache identity |
 | [admin-settings.md](admin-settings.md) | Runtime settings admin — direction-aware atomic writes, write-only secrets, and global/group scope |
+| [admin-fleet-configuration.md](admin-fleet-configuration.md) | Superuser structured configuration publishing, version restore and per-node application evidence |
 | [admin-bouncer.md](admin-bouncer.md) | Bouncer decisions, device investigations, and bot-signature administration with token-safe caching |
 | [admin-security-tickets.md](admin-security-tickets.md) | Ticket queue, KISS detail modal, notes, approvals, and Maestro sync contract |
 | [admin-incidents.md](admin-incidents.md) | Incident/event triage, forensic detail, merge semantics, and sanitized export boundary |
 | [admin-rules.md](admin-rules.md) | Always-inactive RuleSet authoring and the lossless, runtime-effective handler-chain builder |
 | [admin-members.md](admin-members.md) | Global membership table/detail, no-oracle admission, extensible grants, Group-detail composition, and unsupported-operation boundaries |
 | [admin-identity-users.md](admin-identity-users.md) | Global Users table and 14-section detail, system gates, action contracts, and one-time credential invariants |
+| [admin-signin.md](admin-signin.md) | System sign-in page look & feel plus Google/Apple/GitHub provider credentials — one endpoint, changed-paths saves, write-only secrets |
 | [admin-devices-geoip.md](admin-devices-geoip.md) | Fleet device triage, the login-location world map with country drill-down, and the GeoIP dossier — expiry-aware enforcement, the never-cached raw provider record, and the backend traps the port encodes |
 | [admin-jobs.md](admin-jobs.md) | Jobs engine — runner fleet, per-channel queue depth, the segmented job table with armed cancel and republishing retry, the dry-run-first control plane, scheduled tasks with a global-only gate, and the thirteen backend corrections the port encodes |
 | [admin-network-security.md](admin-network-security.md) | Perimeter control — blocked IPs, the firewall log, kernel IP sets and the geofencing page (posture, rules, simulator, evidence, exemptions), with the DSL projection and every backend correction the port encodes |

package/docs/admin-fleet-configuration.md

@@ -0,0 +1,50 @@
+# Fleet Configuration
+
+The Operations → Fleet Configuration page uses `/api/account/admin/fleet`.
+Only literal superusers see the section. An empty permission any-of array uses
+the existing superuser bypass and refuses even the global `admin` grant; the
+page checks `is_superuser === true` before fetching. Backend authority remains
+mandatory, including rejection of diagnostic/key-backed sessions and fresh auth.
+
+Applications register their schema in django-mojo. The page renders the returned
+section, label, description, default, type and restart requirement; no application
+setting names are hardcoded. Each field defaults to Keep current value. Set value
+and Remove published override are explicit actions. Clearing falls back to base
+configuration/default; it does not promise erasure of a bootstrap secret.
+
+Secret inputs start blank, never hold masked placeholders, and blank replacement
+preserves the existing secret. Values stay in the form until an imperative POST;
+secret-bearing writes bypass TanStack MutationCache. Secret current/default fields
+are removed before Query cache storage. The revision-bound publish/restore/apply
+POSTs use `withFreshAuth` and show failures without claiming success. Schema/type
+validation is repeated by the server; browser validation is only feedback.
+
+Publication means published to S3, never applied. Apply now starts a fixed
+asynchronous sync operation and polls its ID until terminal operation status. The
+short job completes after dispatching sync; completed job status does not stop
+polling. Each operation read freshly observes activation until healthy or timed
+out; failed, expired or canceled jobs also stop polling. The expected
+node roster includes missing nodes. Installed, restart requested, restarted and
+healthy remain separate evidence. Only positive installed + restarted + health
+results from every expected node with the explicit
+`request_service_jobs_and_dependencies` health scope justify fleet completion.
+Missing or older health scopes remain unconfirmed, including per-node health and
+restart confirmation, and prompt a backend upgrade. Health covers the
+request service and dependencies where enabled, plus the job engine and scheduler
+with their startup-loaded revision. Worker-only nodes need no request service.
+Draining an old engine is not proof that its replacement has loaded the revision.
+Timed-out, failed, superseded and unknown results stay visible. Refresh status observes the
+normal timer workflow even when Apply now was not used.
+
+History contains only version IDs and timestamps. Restore publishes the selected
+version as a new revision using the current expected revision. Secrets are neither
+shown nor compared. Concurrent publication rejects the stale revision; refresh
+before retrying. Settings edits are tied to their loaded publication revision.
+
+Verify with `npm run verify:admin-fleet`, `npm run typecheck`, `npm run build`, and
+browser checks of both themes. The Settings showcase includes a partial-convergence
+example. Mock Portal uses representative registered settings and an offline node.
+
+Django receives this page only after a canonical Portal artifact is built and
+vendored; follow `docs/admin-artifact.md` and the Django vendor tool. Ordinary
+Vite build output is not the canonical artifact.

package/docs/admin-push.md

@@ -6,38 +6,117 @@ Import `PushPage`, its individual panels/pages, the canonical push models, API h
 
 The page has six possible tabs: Your stats, Global metrics, Devices, Deliveries, Templates, and Config. Stats are authenticated caller data. Every other tab is independently filtered by its exact permission clause, and only the active authorized panel mounts, so hidden/inactive surfaces issue no requests.
 
-`push_surface` is registered with `registerNonFilterParams` at module load. It survives table writes but never becomes a Django lookup or filter pill. Changing tabs replaces the flat URL params with only `push_surface`, intentionally clearing search, sort, paging, and filters that belong to the prior model.
+`push_surface` is registered with `registerNonFilterParams` at module load. It survives table writes but never becomes a Django lookup or filter pill. Changing tabs retains only `push_surface` and the showcase host's `demo` selector, clearing search, sort, paging, and filters belonging to the prior model. Showcase registers `demo` as a non-filter param at boot, so table writes keep the selected demo without sending it as a model lookup.
 
 ## Exact permissions
 
-All UI clauses carry the `sys.` namespace and are ANY-of:
+All UI clauses carry the `sys.` namespace. Alternatives within a clause are ANY-of:
 
 - Devices view: `view_devices | manage_devices | comms | owner | manage_users`; save: `manage_devices | comms | owner`.
 - Deliveries view: `view_notifications | manage_notifications | comms | owner | manage_users`; save: `manage_notifications | comms`.
 - Templates view: `manage_notifications | manage_groups | comms | owner | manage_users`; save: `manage_notifications | manage_groups | comms`.
 - Config view/save: `manage_push_config | manage_groups | comms`.
 - Config connection test: `manage_push_config | comms`.
+- Device test: `send_notifications | comms` **AND** the Devices view clause above.
 - Global metrics: `view_metrics | metrics`, with `account="global"`.
 
 `sys.users` is deliberately absent: it is not in `RegisteredDevice.RestMeta.VIEW_PERMS`. The Stats endpoint requires authentication only and always scopes all five keys to `request.user`.
 
+Device inspection or config management alone never enables a test send. The backend separately enforces global `send_notifications | comms` and visibility of the selected registration; invisible and missing devices both return 404. Config checks require global `manage_push_config | comms`, independently of config editing. Group/member grants, API keys, and key-backed sessions cannot satisfy these test-action gates.
+
 ## Projection and ownership boundaries
 
 Every model pins a `basic` or `default` graph, allowlists list params, and positively projects rows before Query or Mutation cache reconciliation. RegisteredDevice never retains `device_token`; Delivery never retains `platform_data`, and its arbitrary `data_payload` is not retained by the UI projection. Related users are reduced to id plus a short display label—never email, phone, metadata, or an expanded user graph. Template JSON objects accept only a bounded shallow scalar projection on reads.
 
+The additional evidence retained by the UI is:
+
+| Model / result | Retained fields and fallback |
+|---|---|
+| `PushDeviceRow` | `is_active` is boolean or null; an older backend with no field shows “Activity unknown”. |
+| `PushConfigRow` | `fcm_project_id` (max 200 characters), `fcm_client_email` (max 254), and boolean/null `has_fcm_credentials`. Missing metadata is “Not reported” / “Presence not reported”; credential presence is not verification. |
+| `PushDeliveryRow` | `push_outcome` allowlists `accepted`, `delivered`, `simulated`, `rejected`, `blocked`, `unknown`, `pending`, `sent`, and `failed`; otherwise null, with display falling back to stored `status`. |
+| `PushTestConfig` | Positive safe-integer `id`, `name` (max 100), `group` (safe-integer id/name up to 120 characters, or explicit null for system default), `fcm_project_id` (max 200), `test_mode`, `is_active`, `has_fcm_credentials`. No service-account email or secret material. |
+| `PushTestResult` | `success`, `outcome`, local `message`, allowlisted/null `error_code`, success-only `message_id` (max 500), positive safe-integer/null `delivery_id` and `device_id`, and projected/null `config`. |
+
+Test results live in the open dialog, outside Query and Mutation caches. Provider messages and raw error bodies are replaced by local copy; unknown error codes are discarded. `PushReadiness` retains only `ready`, local `message`, `device_id`, and projected `config`.
+
 `PushDeviceModel` now lives canonically in `admin/messaging/push`. The former `admin/identity/users/models.ts` definition is a compatibility re-export of the same object, so User Detail and the global Push page share one endpoint definition and Query key.
 
 ## FCM credentials and actions
 
 FCM writes are imperative and cache-free. A service account textarea is an uncontrolled DOM ref and never prefills. Blank means untouched and is omitted. Replacement must parse to an object with `type="service_account"`, `project_id`, `client_email`, and a PEM `private_key`. Clear sends `null` only after explicit confirmation. Empty replacement is impossible, and server responses are sanitized before cache reconciliation.
 
-Connection testing calls only `POST /api/account/devices/push/config/<id>/test` with an empty body. The backend uses its dummy token to validate credentials. The portal never accepts a device token. It also does not expose `/send`, caller `/test`, delivery retry, device registration/unregistration, or any delete action.
+### Saved configuration check
+
+`testPushConfigConnection(id)` calls `POST /api/account/devices/push/config/<id>/test` with `{}`. The backend authenticates with FCM and submits a validation-only message, including when `test_mode=true` or the selected config is inactive. It sends no device notification and does not activate the config. The portal never accepts a raw device token.
+
+The adapter accepts success only when the envelope has not failed, `success === true`, `outcome === "validated"`, `validation_only === true`, and `message_id` matches `projects/<project>/messages/<reference>`. Missing/malformed verdicts, simulated legacy responses, and provider rejections cannot display a verified connection. Backend HTTP 400 failures retain safe diagnostic data; the adapter returns a failed `PushTestResult` for the dialog to display.
+
+“Check FCM connection” lives in the config header menu. The result and check time remain visible in Overview and Connection for that saved record/revision. Checks lock duplicate checks, editing, and active-state changes while pending. Editing or changing active state clears the result; record revision, permission, caller, or mount changes invalidate late completions. This is evidence from the current view, not a persisted credential-verification flag.
+
+### One registered device
+
+The device header's “Send test push” opens a focused dialog. The API helpers use the existing test endpoint:
+
+| Helper | Request | Purpose |
+|---|---|---|
+| `fetchPushDeviceReadiness(42)` | `GET /api/account/devices/push/test?device_id=42` | Local readiness; no FCM traffic. |
+| `sendPushDeviceTest(42, title, message)` | `POST /api/account/devices/push/test` with `{"device_id":42,"title":"Push test","message":"This is a test notification."}` | One real notification to the selected registration. |
+
+`device_id` here is the numeric database `id`, not the app-provided string `device_id` used for registration. The portal never calls the caller-wide POST variant without a selector. The backend resolves the device owner's active org config, falling back to the active system default; the dialog shows the device, user, config ID/name, scope, and FCM project actually reported by readiness or the send result.
+
+Readiness must explicitly match the requested device and include an active config with credentials present and simulation disabled. Inactive registration, push disabled, an opted-out `test` category, missing token/config/credentials, or simulation prevents sending. Readiness does not verify provider credentials or device reachability. Unknown/malformed readiness disables Send rather than guessing.
+
+The dialog defaults to title `Push test` and message `This is a test notification.`; inputs must be nonblank and fit 200/1000 characters. A single pending guard prevents duplicate submissions and locks fields, Cancel, Escape, and backdrop dismissal during sending. Each dialog permits one completed attempt; reopen it to obtain fresh readiness before another. Permission loss hides stale results; settled requests still unlock dismissal. Every attempt invalidates device, delivery, and caller-stat queries in `finally`.
+
+Device results require explicit `success === true`, `outcome === "accepted"`, a provider message reference, and the requested `device_id`. Handled backend failures may be HTTP 200 with `data.success=false`; inspect the projected result. A failed envelope cannot establish success. Uncertain transport/malformed responses become `unknown`, and known HTTP 400/401/403/404 refusals without structured evidence become blocked. There is no automatic resend.
+
+The portal exposes no general `/send`, caller-wide test, delivery retry, device registration/unregistration, or delete action.
+
+All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Device record editing and delivery mutation remain absent from this page.
+
+## Outcomes and delivery evidence
+
+Test dialogs keep a visible result label, local explanation, check time, and delivery record ID when available:
+
+| Outcome | Meaning |
+|---|---|
+| `validated` | FCM connection verified; no notification delivered. |
+| `accepted` | FCM accepted the notification; the operator must check the selected device for receipt. |
+| `rejected` | FCM refused the request; show the safe diagnostic. |
+| `blocked` | Readiness, credentials, authentication, or request refusal prevented a successful test. |
+| `unknown` | Acceptance is uncertain. Check the device and delivery history before another test; do not label it failed or retry automatically. |
 
-All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Devices and deliveries remain investigative here.
+Delivery lists/details prefer `push_outcome` over `status`. `simulated` is explicitly shown as no FCM send, even though the stored status is `sent`. `unknown` remains pending; provider acceptance alone does not mark a record delivered. Older `sent` records are described as lacking acceptance/receipt evidence. Status filtering and sorting still use the stored status field, not the derived outcome. The caller-stat tile is “Recorded sent” because its count may include simulations.
 
 ## Modal lifecycle convention
 
 See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
-Config/template active-state controls live in the detail header. Config saves
-retain write-only credential handling, and test sends keep their separate gate.
+Config/template active-state controls live in the detail header. Device details
+use Overview/Preferences with active and push-state chips; delivery details use
+Notification/Delivery with outcome explanations. Templates use
+Overview/Notification/Variables; configs use Overview/Connection with scope,
+send-mode, credential-presence, and service-account metadata.
+
+Config/template editors keep one pending save guard and protect Escape/backdrop
+dismissal as well as Cancel. Config saves retain write-only credential handling;
+device test sends use their separate permission AND and dismissal lock.
+
+## Showcase and verification
+
+Open `#/?demo=admin-push` in Showcase. Its banner explicitly identifies
+local fixtures: connection checks and test pushes there never contact FCM or
+deliver notifications. Fixtures exercise system/org config selection, disabled
+push, simulation blockers, safe metadata, and a selected-device accepted result
+with a delivery row and no delivered timestamp. Switching Push tabs preserves
+`demo=admin-push`; model filtering never consumes that host selector.
+
+`npm run verify:admin-push` runs both `scripts/verify-admin-push.mjs` (mock wire,
+permissions, projections, credentials, and target selection) and
+`scripts/verify-push-tests.mjs` (mounted dialog/adapters). The latter covers strict
+provider verdicts, malformed/mismatched responses, revision/permission ownership,
+persistent results, duplicate-send prevention, pending dismissal, and cache
+isolation. JSDOM assertions do not prove native dialog layout or stacking;
+complete browser verification in both themes and a narrow viewport, including
+the device test, configuration check, and nested editors.

package/docs/admin-settings.md

@@ -33,6 +33,16 @@ queries `/api/group`, and preserves that scope on save. New settings default to
 Global. Delete is intentionally absent because live `Setting.RestMeta` does not
 declare deletion.
 
+## Viewing values
+
+JSON objects and arrays show a compact type/count summary in the list. Long or
+multiline text shows a single-line preview, capped at 80 characters. Select the
+row to open the full value in the existing detail
+modal. JSON uses the shared `JsonBlock` viewer, expanded initially, with syntax
+highlighting, Show/Hide, Copy, and a scrollable body. Other text preserves line
+breaks in a scrollable area; invalid JSON remains plain text. Secret values stay
+masked in both views.
+
 ## Atomic write contract
 
 Use `saveSettingAtomic()` / `buildSettingPayload()` rather than a generic

package/docs/admin-signin.md

@@ -0,0 +1,73 @@
+# Sign-in admin (#5547)
+
+Import `SigninPage`, `SIGNIN_ADMIN_SECTION`, the permission clause and the API
+helpers from `portal-mojo/admin` (or `portal-mojo/admin/identity`). The section
+registers one global route, `/system/sign-in`, under **Identity & Access**,
+gated by `SIGNIN_ADMIN_PERMISSIONS` = `['sys.manage_settings', 'sys.admin']`
+(superusers pass). Admin global scope masks any outer product group.
+
+The page has two parts:
+
+- **Look & feel** — the SYSTEM hosted login/registration page: branding,
+  layout/appearance/accent color, hero panel, sign-in heading/copy/methods,
+  registration, custom CSS. It edits the same keys a group admin edits in the
+  group **Configure Auth** dialog; a group's own settings still override these.
+- **Providers** — one card each for Google, Apple and GitHub: an Enabled
+  switch, a read-only callback URL with a Copy button, the credential fields,
+  a Ready / Needs setup badge, and a link to the provider's console.
+
+KISS by design: trusted admins, no step-up auth, no confirmation beyond a
+browser `confirm()` before clearing a stored value.
+
+## Wire contract
+
+One endpoint, both methods, django-mojo envelope.
+
+`GET /api/account/admin/signin` → `{schema_version, auth, editable, options, providers}`
+
+- `auth` is `public_auth_config` of the resolved system config
+  (`{theme, login, registration}`).
+- `editable` lists the flat dotted paths the POST accepts. The page renders
+  only fields whose path is listed, so the backend can narrow it.
+- `options` carries the allowed tokens for methods, layouts, appearances,
+  hero image positions and passkey prompts. Legacy layouts `card` /
+  `fullscreen` display as `compact` / `branded-panel`; any other unknown select
+  value falls back to the first option with a `console.warn`.
+- `providers[]`: `{name, label, enabled, ready, missing, callback_url,
+  console_url, help, fields[]}`; each field is `{key, label, secret,
+  multiline, configured, source, value, hint}`. `source` is `admin`,
+  `deployment` (shown as "Set in server config") or `none`. Secret fields
+  never carry `value`; `hint` (e.g. `…a1b2`) is shown when present.
+
+`POST /api/account/admin/signin` returns the same full payload, which the page
+writes straight into its query cache (`SIGNIN_QUERY_KEY`).
+
+- Look & feel: `{auth: {"theme.app_title": "…", "login.methods": […]}}` —
+  only the paths whose value differs from the loaded payload, sent by the
+  explicit **Save** button. Password is locked on in the sign-in methods picker;
+  the server rejects a list without it (400).
+- Provider: `{provider, values, enabled}`. In `values`, an omitted key or
+  `""` keeps the stored value and `null` clears it. The card's **Save** sends
+  only fields the admin typed into; **Clear…** (shown for `source: "admin"`)
+  confirms, then sends `null` at once. The **Enabled** switch saves
+  immediately with `{provider, enabled}`, which adds/removes the provider from
+  both `login.methods` and `registration.methods`.
+- Errors are `{status: false, error}` (HTTP 400). The client rejects them; the
+  page shows the message inline and as a toast and keeps the unsaved edits.
+
+Secrets are entered in password inputs (the Apple `.p8` key in a textarea)
+and cleared from local state after a successful save.
+
+## Mock
+
+`src/client/mock.ts` implements the endpoint: global `manage_settings` /
+`admin` gate (401 anonymous, 403 otherwise), `editable`-only writes with the
+option and password rules, and credential storage. Seed: Apple has Team ID and
+Services ID stored in the Admin (missing Key ID and private key), Google has
+nothing, GitHub is configured by the deployment. Saved look & feel lands in a
+system override that `/api/auth/config` layers between the deployment config
+and group overrides, so the public config reflects saves. An Admin-stored
+credential wins over the deployment value; clearing it falls back to the
+deployment value.
+
+Verify with `npm run verify:admin-signin`.

package/docs/realtime.md

@@ -19,6 +19,11 @@ disable this shared provider.
   `auth_success`. An auth error closes and suspends the connection until the
   token value changes.
 - Heartbeat is a `ping` every 20 seconds with a 10-second `pong` deadline.
+  A server-initiated `{type:'ping'}` (django-mojo 1.32+ sends one every 20
+  seconds and culls a socket silent for 90) is answered at once with
+  `{type:'pong'}` while ready, clears the pending `pong` deadline, and is never
+  dispatched to consumers. Answering from the message handler keeps the socket
+  alive while a background tab throttles the client's own ping timer.
   Reconnect uses capped jittered backoff. Pre-accept close code 4429 enforces at
   least 60 seconds, and focus/visibility cannot bypass that deadline.
 - Desired topics are refcounted and replay after authentication. Operations are

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.4",
+    "version": "0.2.5",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/domains/identity.ts

@@ -2,6 +2,7 @@ import type { AdminSection } from '../core';
 import { GLOBAL_CREDENTIAL_PERMS } from '../credentials/models';
 import { MEMBER_READ_PERMISSIONS } from '../identity/members/models';
 import { USER_VIEW_PERMISSIONS } from '../identity/users/models';
+import { SIGNIN_ADMIN_PERMISSIONS } from '../signin/api';
 
 export const USERS_ADMIN_SECTION: AdminSection = {
     id: 'users', basePath: '', title: 'Users', icon: 'bi-people', navigationGroup: 'identity-access', permissions: USER_VIEW_PERMISSIONS,
@@ -21,4 +22,9 @@ export const CREDENTIALS_ADMIN_SECTION: AdminSection = {
     ],
 };
 
-export const IDENTITY_ADMIN_SECTIONS = [USERS_ADMIN_SECTION, MEMBERS_ADMIN_SECTION, CREDENTIALS_ADMIN_SECTION] as const;
+export const SIGNIN_ADMIN_SECTION: AdminSection = {
+    id: 'signin', basePath: 'system/sign-in', title: 'Sign-in', icon: 'bi-box-arrow-in-right', navigationGroup: 'identity-access', permissions: SIGNIN_ADMIN_PERMISSIONS,
+    routes: [{ path: '', loadComponent: () => import('../signin/SigninPage').then(({ SigninPage }) => ({ default: SigninPage })), permissions: SIGNIN_ADMIN_PERMISSIONS }],
+};
+
+export const IDENTITY_ADMIN_SECTIONS = [USERS_ADMIN_SECTION, MEMBERS_ADMIN_SECTION, CREDENTIALS_ADMIN_SECTION, SIGNIN_ADMIN_SECTION] as const;

package/src/admin/domains/operations.ts

@@ -6,6 +6,13 @@ export const SETTINGS_ADMIN_SECTION: AdminSection = {
     id: 'settings', title: 'Settings', icon: 'bi-gear', navigationGroup: 'operations', permissions: SETTINGS_PERMISSIONS,
     routes: [{ path: '', loadComponent: () => import('../settings/SettingsPage').then(({ SettingsPage }) => ({ default: SettingsPage })), permissions: SETTINGS_PERMISSIONS }],
 };
+// Empty any-of permissions admit only the existing literal-superuser bypass.
+// A global admin permission alone must not expose this configuration surface.
+export const FLEET_CONFIGURATION_ADMIN_SECTION: AdminSection = {
+    id: 'fleet-configuration', title: 'Fleet Configuration', icon: 'bi-hdd-network',
+    navigationGroup: 'operations', permissions: [],
+    routes: [{ path: '', loadComponent: () => import('../fleet-configuration/FleetConfigurationPage').then(({ FleetConfigurationPage }) => ({ default: FleetConfigurationPage })) }],
+};
 export const JOBS_ADMIN_SECTION: AdminSection = {
     id: 'jobs', title: 'Jobs', icon: 'bi-cpu', navigationGroup: 'operations', permissions: [...new Set([...JOBS_VIEW_PERMS, ...SCHEDULED_TASK_VIEW_PERMS])],
     routes: [
@@ -15,4 +22,4 @@ export const JOBS_ADMIN_SECTION: AdminSection = {
         { path: 'scheduled-tasks', label: 'Scheduled Tasks', loadComponent: () => import('../jobs/ScheduledTasksPage').then(({ ScheduledTasksPage }) => ({ default: ScheduledTasksPage })), permissions: SCHEDULED_TASK_VIEW_PERMS },
     ],
 };
-export const OPERATIONS_ADMIN_SECTIONS = [SETTINGS_ADMIN_SECTION, JOBS_ADMIN_SECTION] as const;
+export const OPERATIONS_ADMIN_SECTIONS = [SETTINGS_ADMIN_SECTION, FLEET_CONFIGURATION_ADMIN_SECTION, JOBS_ADMIN_SECTION] as const;

package/src/admin/fleet-configuration/FleetConfigurationPage.tsx

@@ -0,0 +1,171 @@
+import { useRef, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMe } from '../../client/runtime';
+import { modal } from '../../ui';
+import {
+    FLEET_ENDPOINT, FLEET_HEALTH_SCOPE, displayFleetValue, fleetChange, fleetIsHealthy, operationFinished,
+    readFleet, readFleetHistory, readFleetOperation, writeFleet,
+    type FleetChanges, type FleetEntry, type FleetOperation, type FleetPublication, type FleetReport, type FleetState,
+} from './data';
+
+function SettingInput({ entry, disabled }: { entry: FleetEntry; disabled: boolean }) {
+    const [mode, setMode] = useState('keep');
+    const current = entry.sensitive ? (entry.configured ? 'Configured (hidden)' : 'Not configured') : displayFleetValue(entry.current);
+    const initial = entry.sensitive ? '' : entry.value_type === 'string' ? String(entry.current ?? '')
+        : entry.value_type === 'boolean' ? String(entry.current === true)
+        : entry.current == null ? '' : JSON.stringify(entry.current);
+    const control = { name: `${entry.key}:value`, className: 'input', disabled, defaultValue: initial };
+    return <div className="panel panel-pad" style={{ minWidth: 0 }}>
+        <h3>{entry.label}</h3><p className="dim">{entry.description}</p>
+        <p style={{ overflowWrap: 'anywhere' }}><b>Current:</b> {current}</p>
+        {!entry.sensitive && <p className="dim">Default: {displayFleetValue(entry.default)}</p>}
+        <p><span className="badge">{entry.restart_required ? 'Restart required' : 'No restart required'}</span></p>
+        <label className="field"><span className="field-label">Proposed change for {entry.label}</span>
+            <select className="input" name={`${entry.key}:mode`} value={mode} disabled={disabled} onChange={(event) => setMode(event.target.value)}>
+                <option value="keep">Keep current value</option><option value="set">{entry.sensitive ? 'Replace secret' : 'Set value'}</option>
+                {entry.overridden && <option value="clear">Remove published override</option>}
+            </select>
+        </label>
+        {mode === 'set' && <label className="field"><span className="field-label">{entry.sensitive ? 'Secret replacement' : 'Proposed value'}</span>
+            {entry.value_type === 'boolean' ? <select {...control}><option value="true">True</option><option value="false">False</option></select>
+                : entry.value_type === 'list' || entry.value_type === 'object' ? <textarea {...control} rows={4} autoComplete="off" spellCheck={false} />
+                    : <input {...control} type={entry.sensitive ? 'password' : entry.value_type === 'integer' ? 'number' : 'text'}
+                        autoComplete="off" spellCheck={false} min={entry.min_value ?? undefined} max={entry.max_value ?? undefined} maxLength={entry.max_length} step={1} />}
+            <span className="field-help">{entry.sensitive ? 'Leave blank to preserve the existing secret. Secrets are never shown in history.'
+                : entry.value_type === 'list' || entry.value_type === 'object' ? `Enter a JSON ${entry.value_type}; at most ${entry.max_items ?? 100} entries.` : 'Validated again by the server before publication.'}</span>
+        </label>}
+        {mode === 'clear' && <p className="text-warn">Removes this published override; the node’s base configuration or application default will apply.</p>}
+    </div>;
+}
+
+function FleetEditor({ state, busy, onPublish }: { state: FleetState; busy: boolean; onPublish: (changes: FleetChanges) => Promise<void> }) {
+    const form = useRef<HTMLFormElement>(null);
+    const [error, setError] = useState('');
+    const sections = [...new Set(state.entries.map((entry) => entry.section))];
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault(); setError('');
+        try {
+            const fields = new FormData(form.current!);
+            const changes: FleetChanges = {};
+            for (const entry of state.entries) {
+                const change = fleetChange(entry, String(fields.get(`${entry.key}:mode`) ?? 'keep'), String(fields.get(`${entry.key}:value`) ?? ''));
+                if (change) changes[entry.key] = change;
+            }
+            if (!Object.keys(changes).length) { setError('Choose at least one change before publishing.'); return; }
+            await onPublish(changes);
+        } catch (reason) { setError(reason instanceof Error ? reason.message : 'Could not publish configuration'); }
+    };
+    return <form ref={form} onSubmit={submit}>
+        <fieldset disabled={busy} style={{ border: 0, padding: 0, margin: 0, minWidth: 0 }}>
+            {sections.map((section) => <section key={section} style={{ marginBottom: 20 }}><h2>{section}</h2>
+                <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 320px), 1fr))', gap: 12 }}>
+                    {state.entries.filter((entry) => entry.section === section).map((entry) => <SettingInput key={entry.key} entry={entry} disabled={busy} />)}
+                </div></section>)}
+            {!state.entries.length && <p>No settings have been registered and delegated for this application.</p>}
+            {error && <p className="form-alert" role="alert">{error}</p>}
+            <button className="btn btn-primary" type="submit" disabled={busy || !state.publish_configured || !state.entries.length}>Publish</button>
+        </fieldset>
+    </form>;
+}
+
+export function FleetNodeStatus({ report, revision }: { report: FleetReport; revision: string | null }) {
+    const healthy = fleetIsHealthy(report);
+    const jobsCovered = report.health_scope === FLEET_HEALTH_SCOPE;
+    return <section className="panel panel-pad" aria-label="Fleet convergence" style={{ marginTop: 20 }}>
+        <h2>Fleet convergence</h2><p role="status" className={healthy ? 'text-ok' : 'text-warn'}>
+            {healthy ? 'Applied and healthy on every expected node' : `Not confirmed healthy everywhere — ${report.status}`}</p>
+        <p className="dim" style={{ overflowWrap: 'anywhere' }}>Target revision: {revision ?? 'Not published'}{report.observed_at ? ` · Observed ${report.observed_at}` : ''}</p>
+        {report.error_code && <p className="form-alert">{report.error_code}</p>}
+        {!report.nodes.length ? <p>No node results are available. Publication alone does not establish fleet health.</p>
+            : <div className="tbl-scroll"><table className="tbl"><thead><tr><th>Node</th><th>Published</th><th>Downloaded / installed</th><th>Restart</th><th>Healthy</th><th>Result</th></tr></thead>
+                <tbody>{report.nodes.map((node) => <tr key={node.hostname}><td>{node.hostname}</td><td>{node.published ? 'Yes' : 'Unconfirmed'}</td>
+                    <td>{node.installed ? 'Yes' : 'Unconfirmed'}</td><td>{jobsCovered && node.restarted ? 'Confirmed' : node.restart_requested ? 'Requested' : 'Unconfirmed'}</td>
+                    <td>{jobsCovered && node.healthy && node.installed && node.restarted && !node.error_code ? 'Yes' : 'Unconfirmed'}</td><td>{node.error_code ?? (!jobsCovered && node.status === 'healthy' ? 'Scope unverified' : node.status)}</td></tr>)}</tbody></table></div>}
+        {!jobsCovered && <p className="text-warn">This report does not verify job engine and scheduler activation. Refresh after upgrading the backend to confirm fleet health.</p>}
+        <p className="dim">Health verifies the request service where enabled, plus the job engine and scheduler. Worker-only nodes do not require a request service. Offline or missing nodes remain unconfirmed.</p>
+    </section>;
+}
+
+function FleetContent({ userId }: { userId: number }) {
+    const queryClient = useQueryClient();
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+    const [notice, setNotice] = useState('');
+    const [editorEpoch, setEditorEpoch] = useState(0);
+    const [operationId, setOperationId] = useState<string | null>(null);
+    const queryKey = [FLEET_ENDPOINT, userId];
+    const stateQuery = useQuery({ queryKey, queryFn: readFleet, refetchOnWindowFocus: false, retry: false });
+    const history = useQuery({ queryKey: [...queryKey, 'history'], queryFn: readFleetHistory, retry: false });
+    const operation = useQuery({ queryKey: [...queryKey, 'operation', operationId], enabled: operationId != null,
+        queryFn: () => readFleetOperation(operationId!), retry: false,
+        refetchInterval: (query) => query.state.error || (query.state.data && operationFinished(query.state.data)) ? false : 3000 });
+    const state = stateQuery.data;
+    const refresh = async () => { await Promise.all([stateQuery.refetch(), history.refetch(), ...(operationId ? [operation.refetch()] : [])]); };
+    const run = async (task: () => Promise<void>) => {
+        setBusy(true); setError(''); setNotice('');
+        try { await task(); } catch (reason) { setError(reason instanceof Error ? reason.message : 'Fleet operation failed'); }
+        finally { setBusy(false); }
+    };
+    const publish = async (changes: FleetChanges) => {
+        if (!state || !await modal.confirm({ title: 'Publish fleet configuration?',
+            message: `Publish changes to ${Object.keys(changes).join(', ')}? Config-sync timers will download the new configuration and may restart services. Publication does not confirm that nodes are healthy.`, confirmText: 'Publish' })) return;
+        await run(async () => {
+            const result = await writeFleet<FleetPublication>({ action: 'publish', expected_revision: state.revision, changes });
+            if (result.published !== true) throw new Error('Publication was not confirmed. Reload to check the current revision.');
+            setOperationId(null); setEditorEpoch((value) => value + 1); setNotice('Published to S3. Node application and health are still pending.'); await refresh();
+        });
+    };
+    const apply = async () => {
+        if (!state || !await modal.confirm({ title: 'Apply configuration now?', message: 'Ask every expected node to run its configured sync service now. Services may restart. Results will appear below.', confirmText: 'Apply now' })) return;
+        await run(async () => {
+            const result = await writeFleet<FleetOperation>({ action: 'apply', expected_revision: state.revision });
+            if (!result.operation_id) throw new Error('No apply operation was returned. Refresh node status before retrying.');
+            queryClient.setQueryData([...queryKey, 'operation', result.operation_id], result);
+            setOperationId(result.operation_id); setNotice('Apply requested. Waiting for each node to confirm its result.');
+        });
+    };
+    const restore = async (versionId: string) => {
+        if (!state || !await modal.confirm({ title: 'Restore previous version?', message: 'Publish this previous configuration as a new revision, including its stored secret values. Config-sync timers may restart services. Node health must be checked separately.', confirmText: 'Restore previous version' })) return;
+        await run(async () => {
+            const result = await writeFleet<FleetPublication>({ action: 'restore', expected_revision: state.revision, version_id: versionId });
+            if (result.published !== true) throw new Error('Restore was not confirmed. Reload to check the current revision.');
+            setOperationId(null); setEditorEpoch((value) => value + 1); setNotice('Previous version published as a new revision. Node application and health are still pending.'); await refresh();
+        });
+    };
+    if (!state) return <div className="panel panel-pad"><h1>Fleet Configuration</h1><p role="alert">{stateQuery.error?.message ?? 'Loading configuration…'}</p>
+        {stateQuery.error && <button className="btn" onClick={() => void refresh()}>Retry</button>}</div>;
+    const tracked = operationId && operation.data?.revision === state.revision ? operation.data : null;
+    const evidence = tracked && (!operationFinished(tracked) || Date.parse(tracked.observed_at ?? '') > Date.parse(state.fleet.observed_at ?? '')) ? tracked : state.fleet;
+    const report = stateQuery.error || operation.error ? { ...evidence, status: 'observation_unavailable', healthy_everywhere: false,
+        nodes: evidence.nodes.map((node) => ({ ...node, healthy: false })) } : evidence;
+    return <div className="page" style={{ minWidth: 0, overflowWrap: 'anywhere' }}><header className="page-header"><div><h1>Fleet Configuration</h1>
+        <p className="dim">Publish registered application settings and track their application across your nodes.</p></div></header>
+        <div className="panel panel-pad" style={{ marginBottom: 20 }}><p style={{ overflowWrap: 'anywhere' }}><b>Published to S3:</b> {state.published ? state.revision : 'Not yet published'}</p>
+            <p className="dim">This request’s node loaded revision: {state.loaded_revision ?? 'Not reported'}</p>
+            {!state.publish_configured && <p className="form-alert">Publishing is unavailable until the fleet configuration location, encryption and delegated settings are configured.</p>}
+            <button className="btn" disabled={busy || stateQuery.isFetching} onClick={() => void refresh()}>Refresh status</button>{' '}
+            <button className="btn" disabled={busy || !state.revision || (operation.data != null && !operationFinished(operation.data))} onClick={() => void apply()}>Apply now</button>
+            {notice && <p role="status">{notice}</p>}{(error || stateQuery.error) && <p className="form-alert" role="alert">{error || stateQuery.error?.message}</p>}
+        </div>
+        <FleetEditor key={`${state.revision ?? 'unpublished'}:${editorEpoch}`} state={state} busy={busy} onPublish={publish} />
+        {operation.error && <p className="form-alert" role="alert">Apply status could not be refreshed: {operation.error.message}. Refresh status to check nodes; prior results are not current confirmation.</p>}
+        {tracked && <p role="status">Apply operation: {tracked.status}</p>}
+        <FleetNodeStatus report={report} revision={state.revision} />
+        <section className="panel panel-pad" style={{ marginTop: 20 }}><h2>Version history</h2>
+            {history.error && <p className="form-alert">{history.error.message}</p>}
+            {history.isPending && <p>Loading versions…</p>}
+            {history.data?.versions.map((version) => <div key={version.version_id} style={{ display: 'flex', flexWrap: 'wrap', gap: 12, marginBottom: 12, alignItems: 'center' }}>
+                <span style={{ overflowWrap: 'anywhere', minWidth: 0 }}>{version.published_at ?? 'Time unavailable'} · {version.version_id}{version.current ? ' (current)' : ''}</span>
+                {!version.current && <button className="btn" disabled={busy || !state.publish_configured} onClick={() => void restore(version.version_id)}>Restore previous version</button>}
+            </div>)}
+            {history.data?.versions.length === 0 && <p>No previous versions are available.</p>}
+            {history.data?.truncated && <p className="dim">Only the most recent available versions are shown.</p>}
+        </section></div>;
+}
+
+export function FleetConfigurationPage() {
+    const { data: me, isLoading } = useMe();
+    if (isLoading) return <p>Checking access…</p>;
+    if (me?.is_superuser !== true) return <div className="panel panel-pad">Fleet Configuration requires a superuser account.</div>;
+    return <FleetContent key={me.id} userId={me.id} />;
+}