@lamalibre/create-lamaste 4.3.1 → 4.4.1

package/vendor/serverd/src/lib/plugins.js

@@ -25,6 +25,8 @@ import {
 import { listRegisteredSubScopeNames } from './tickets.js';
 import { getStateDb } from './state-db.js';
 import { revokePluginCapabilitiesFromAgents } from './mtls.js';
+import { withRegistryUserconfig } from './registry-credential.js';
+import { RegistryCredentialError } from '@lamalibre/lamaste/server';
 import {
   bareLamalibrePackageName,
   installedHookEntrySha256,
@@ -69,10 +71,19 @@ async function getStmts() {
       INSERT INTO plugins
         (name, route, display_name, package_name, version, description, capabilities,
          packages, panel, config, modes, hosting, agent, hooks, hooks_entry_sha256,
-         agent_half_pin, status, installed_at, enabled_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         agent_half_pin, settings, status, installed_at, enabled_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
     deleteByName: db.prepare('DELETE FROM plugins WHERE name = ?'),
+    // The relay's cache of the plugin's settings (lib/plugin-settings.js)
+    // goes with its row, and follows its settings schema.
+    deleteSettingsByName: db.prepare('DELETE FROM plugin_settings WHERE plugin = ?'),
+    selectSettingsByName: db.prepare('SELECT * FROM plugin_settings WHERE plugin = ?'),
+    updatePrunedSettings: db.prepare(`
+      UPDATE plugin_settings
+        SET values_json = ?, secrets_set_json = ?, configured = ?, missing_json = ?
+      WHERE plugin = ?
+    `),
     deleteAll: db.prepare('DELETE FROM plugins'),
     updateStatusEnable: db.prepare(`
       UPDATE plugins SET status = 'enabled', enabled_at = ? WHERE name = ?
@@ -125,6 +136,7 @@ function rowToPlugin(row) {
   if (row.hooks != null) entry.hooks = JSON.parse(row.hooks);
   if (row.hooks_entry_sha256 != null) entry.hooksEntrySha256 = row.hooks_entry_sha256;
   if (row.agent_half_pin != null) entry.agentHalfPin = JSON.parse(row.agent_half_pin);
+  if (row.settings != null) entry.settings = JSON.parse(row.settings);
   if (row.enabled_at != null) entry.enabledAt = row.enabled_at;
   return entry;
 }
@@ -183,6 +195,7 @@ export async function writePlugins(data) {
         nullableJson(p.hooks),
         nullableString(p.hooksEntrySha256),
         nullableJson(p.agentHalfPin),
+        nullableJson(p.settings),
         p.status,
         p.installedAt,
         nullableString(p.enabledAt),
@@ -315,6 +328,17 @@ export async function manifestPolicyError(manifest) {
   return null;
 }
 
+/**
+ * What a failed install of `spec` is reported as. A registry that refused
+ * the panel's credential says so (the registry host and the status, from
+ * {@link withRegistryUserconfig}); anything else is npm's failure, whose
+ * output is in the log.
+ */
+function installFailure(spec, err) {
+  const detail = err instanceof RegistryCredentialError ? `: ${err.message}` : '';
+  return `Failed to install "${spec}"${detail}`;
+}
+
 export function installPlugin(packageName, logger) {
   return withPluginLock(async () => {
     // Validate package scope
@@ -347,19 +371,25 @@ export function installPlugin(packageName, logger) {
       }
     }
 
-    // Install the npm package
+    // Install the npm package — from the configured registry, as the
+    // panel's own identity, when a registry credential is set.
     logger.info({ packageName: installSpec }, 'Installing plugin package');
     try {
-      await execa('npm', ['install', '--ignore-scripts', installSpec], {
-        cwd: STATE_DIR,
-        timeout: 120000,
-      });
+      await withRegistryUserconfig(
+        (env) =>
+          execa('npm', ['install', '--ignore-scripts', installSpec], {
+            cwd: STATE_DIR,
+            timeout: 120000,
+            env,
+          }),
+        { log: logger },
+      );
     } catch (err) {
       logger.error(
         { packageName: installSpec, stderr: err.stderr, err: err.message },
         'npm install failed',
       );
-      throw Object.assign(new Error(`Failed to install "${installSpec}"`), { statusCode: 500 });
+      throw Object.assign(new Error(installFailure(installSpec, err)), { statusCode: 500 });
     }
 
     // Read the plugin manifest from the installed package
@@ -448,12 +478,16 @@ export function installPlugin(packageName, logger) {
       hooks: manifest.hooks,
       hooksEntrySha256,
       agentHalfPin,
+      settings: manifest.settings,
       status: 'disabled',
       installedAt: new Date().toISOString(),
     };
 
     s.begin.run();
     try {
+      // No settings are cached for a plugin that is not installed (its
+      // uninstall dropped them); none from before may meet this schema.
+      s.deleteSettingsByName.run(entry.name);
       s.insert.run(
         entry.name,
         entry.route,
@@ -471,6 +505,7 @@ export function installPlugin(packageName, logger) {
         nullableJson(entry.hooks),
         nullableString(entry.hooksEntrySha256),
         nullableJson(entry.agentHalfPin),
+        nullableJson(entry.settings),
         entry.status,
         entry.installedAt,
         null,
@@ -543,10 +578,13 @@ export function uninstallPlugin(name, logger) {
       logger.warn({ err: err.message }, 'Failed to remove plugin state directory');
     });
 
-    // Remove from registry
+    // Remove from registry, with the cache of its settings (the agent half
+    // holds the settings themselves; a purge removed them, or they stay with
+    // the data an agent keeps of it)
     s.begin.run();
     try {
       s.deleteByName.run(name);
+      s.deleteSettingsByName.run(name);
       s.commit.run();
     } catch (err) {
       s.rollback.run();
@@ -593,34 +631,66 @@ const updateRowSql = `
   UPDATE plugins SET
     display_name = ?, version = ?, description = ?, capabilities = ?, packages = ?, panel = ?,
     config = ?, modes = ?, hosting = ?, agent = ?, hooks = ?, hooks_entry_sha256 = ?,
-    agent_half_pin = ?
+    agent_half_pin = ?, settings = ?
   WHERE name = ?`;
 
 /**
  * Rewrite an installed plugin's row from a manifest (an update, or its
  * reversal) with the agent half pinned for that version (null when Lamaste
- * installs none). Status and install time stay.
+ * installs none). Status and install time stay. When the settings schema
+ * changes, the relay's cache of the settings is pruned in the same
+ * transaction — values and secrets whose field changed type or went
+ * (`prunedSettingsCache`) — so no read pairs the new schema with values
+ * stored for the old one: a value whose field became a secret never shows
+ * beside it, and a secret whose field became a plain value is no longer
+ * reported set.
  */
 export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalfPin) {
   const s = await getStmts();
-  s.db
-    .prepare(updateRowSql)
-    .run(
-      nullableString(manifest.displayName),
-      manifest.version,
-      nullableString(manifest.description),
-      JSON.stringify(manifest.capabilities ?? []),
-      nullableJson(manifest.packages),
-      nullableJson(manifest.panel),
-      nullableJson(manifest.config),
-      nullableJson(manifest.modes),
-      manifest.hosting ?? DEFAULT_PLUGIN_HOSTING,
-      nullableJson(manifest.agent),
-      nullableJson(manifest.hooks),
-      nullableString(hooksEntrySha256),
-      nullableJson(agentHalfPin),
-      name,
+  const { prunedSettingsCache } = await import('./plugin-settings.js');
+  s.begin.run();
+  try {
+    const before = s.selectByName.get(name);
+    s.db
+      .prepare(updateRowSql)
+      .run(
+        nullableString(manifest.displayName),
+        manifest.version,
+        nullableString(manifest.description),
+        JSON.stringify(manifest.capabilities ?? []),
+        nullableJson(manifest.packages),
+        nullableJson(manifest.panel),
+        nullableJson(manifest.config),
+        nullableJson(manifest.modes),
+        manifest.hosting ?? DEFAULT_PLUGIN_HOSTING,
+        nullableJson(manifest.agent),
+        nullableJson(manifest.hooks),
+        nullableString(hooksEntrySha256),
+        nullableJson(agentHalfPin),
+        nullableJson(manifest.settings),
+        name,
+      );
+    const pruned = prunedSettingsCache(
+      s.selectSettingsByName.get(name),
+      before?.settings != null ? JSON.parse(before.settings) : null,
+      manifest.settings ?? null,
     );
+    if (pruned?.delete) {
+      s.deleteSettingsByName.run(name);
+    } else if (pruned) {
+      s.updatePrunedSettings.run(
+        JSON.stringify(pruned.values),
+        JSON.stringify(pruned.secretsSet),
+        pruned.configured ? 1 : 0,
+        JSON.stringify(pruned.missing),
+        name,
+      );
+    }
+    s.commit.run();
+  } catch (err) {
+    s.rollback.run();
+    throw err;
+  }
 }
 
 /**
@@ -637,13 +707,18 @@ export function replacePluginPackage(name, packageName, version, logger) {
     assertSafeLamalibrePackage(spec);
     logger?.info({ name, spec }, 'Installing plugin package version');
     try {
-      await execa('npm', ['install', '--ignore-scripts', spec], {
-        cwd: STATE_DIR,
-        timeout: 120000,
-      });
+      await withRegistryUserconfig(
+        (env) =>
+          execa('npm', ['install', '--ignore-scripts', spec], {
+            cwd: STATE_DIR,
+            timeout: 120000,
+            env,
+          }),
+        { log: logger },
+      );
     } catch (err) {
       logger?.error({ spec, stderr: err.stderr, err: err.message }, 'npm install failed');
-      throw Object.assign(new Error(`Failed to install "${spec}"`), { statusCode: 502 });
+      throw Object.assign(new Error(installFailure(spec, err)), { statusCode: 502 });
     }
     const require = createRequire(`${STATE_DIR}/`);
     const manifestPath = require.resolve(`${bare}/lamaste-plugin.json`);

package/vendor/serverd/src/lib/registry-credential.js

@@ -12,6 +12,13 @@
  *   install within the hour and limited to ten new tokens per agent per
  *   hour.
  *
+ * The panel's own npm calls — installing a plugin, staging an update with
+ * `npm pack`, pinning an agent half with `npm view` — go through
+ * {@link withRegistryUserconfig}: with a credential configured, npm is
+ * routed to its registry for its scope and authenticated with the service
+ * token through a throw-away userconfig; without one, npm runs as it is
+ * configured on the machine (the public registry by default).
+ *
  * Also the one piece of policy that belongs here: when a user loses a
  * `feria-*` group or is deleted, their registry tokens are revoked (best
  * effort, never blocks the user operation).
@@ -26,6 +33,7 @@ import {
   revokeRegistryTokensForOwner,
   lostFeriaGroups,
   readOidcClientSecret,
+  withRegistryUserconfig as withRegistryUserconfigCore,
   RegistryServiceTokenCache,
   AgentTokenBroker,
   RegistryCredentialError,
@@ -102,6 +110,35 @@ async function serviceToken(config) {
   return (await serviceTokens.resolve(config, await oidcDeps(config))).token;
 }
 
+/**
+ * Run `fn(env)` — one npm call of the panel's own — against the configured
+ * registry: with a credential, `env` names an isolated userconfig (0600,
+ * removed afterwards) routing the credential's scope to its registry with
+ * the panel's service token; a `401` refreshes the token once and retries.
+ * Without a credential `fn({})` runs npm as the machine configures it.
+ * A credential file that cannot be read fails the call rather than
+ * silently installing from the public registry.
+ *
+ * @template T
+ * @param {(env: Record<string, string>) => Promise<T>} fn
+ * @param {{ log?: import('pino').Logger | undefined }} [options]
+ * @returns {Promise<T>}
+ */
+export async function withRegistryUserconfig(fn, options = {}) {
+  const config = await readRegistryCredentialConfig();
+  if (!config) return fn({});
+  const deps = await oidcDeps(config);
+  return withRegistryUserconfigCore(
+    config,
+    async ({ refresh }) => {
+      if (refresh) serviceTokens.invalidate();
+      return (await serviceTokens.resolve(config, deps)).token;
+    },
+    fn,
+    { log: options.log },
+  );
+}
+
 /**
  * The calling agent's registry token: the cached one when it is still good
  * for an install, otherwise a freshly brokered one-hour token — unless the

package/vendor/serverd/src/lib/tunnel-hooks.js

@@ -9,6 +9,11 @@
  * up, or after a restart of the panel. The agent side of the pipeline runs
  * on the agent (its sync follows the relay's view of the tunnel).
  *
+ * Whenever the plugin comes up — after a `down`, or first seen up — the
+ * relay also re-reads its settings from the agent half: they may have
+ * changed while the relay could not see it (a restore, a retyped field
+ * dropped by a new version).
+ *
  * Calls for one plugin are serialised and run beside the monitor, which
  * does not wait for them.
  */
@@ -21,6 +26,7 @@ import {
 } from './plugin-hooks.js';
 import { runRelayHook } from './relay-hooks.js';
 import { rememberTunnelFallback } from './request-hooks.js';
+import { refreshPluginSettingsBestEffort } from './plugin-settings.js';
 
 const chains = new Map();
 
@@ -34,6 +40,11 @@ export function onHealthTransition(plugin, before, after, logger) {
     .then(() => runTunnelHook(plugin, before, after, logger))
     .catch((err) => {
       logger?.error({ plugin, err: err?.message }, 'Tunnel-state hook pipeline failed');
+    })
+    .then(async () => {
+      if (after.state === 'up' && before?.state !== 'up') {
+        await refreshPluginSettingsBestEffort(plugin, logger);
+      }
     });
   chains.set(plugin, next);
   next.finally(() => {

package/vendor/serverd/src/routes/management/plugins.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AGENT_LABEL_REGEX } from '@lamalibre/lamaste';
+import { AGENT_HALF_SETTINGS_MAX_BYTES, AGENT_LABEL_REGEX } from '@lamalibre/lamaste';
 import {
   readPlugins,
   installPlugin,
@@ -35,6 +35,11 @@ import {
   listPluginOperations,
   takeOperationReveal,
 } from '../../lib/plugin-operations.js';
+import {
+  attachSettingsSummaries,
+  getPluginSettingsView,
+  updatePluginSettings,
+} from '../../lib/plugin-settings.js';
 import { actorFromRequest, certSerialFromRequest } from '../../lib/actor.js';
 import { recordAudit } from '../../lib/audit.js';
 import {
@@ -112,13 +117,57 @@ function operationErrorBody(err, fallback) {
   };
 }
 
+/**
+ * The error body of a refused settings read or change: the message and what
+ * a client acts on — `code` (`no_settings`, `operation_running` with the
+ * operation's id, `hosting_offline` with the `hosting`, `revision_mismatch`
+ * with the current `revision`, `schema_mismatch`, `settings_unsupported`,
+ * `refused`, `timeout`, …) and `errors` per field (400: the panel's check,
+ * 422: the agent half's). Built from what the settings library put on the
+ * error — never from the request body.
+ */
+function settingsErrorBody(err, fallback) {
+  // Only the settings library's own refusals carry a status; anything else
+  // is answered without its message.
+  if (!err.statusCode) return { error: fallback };
+  return {
+    error: err.message,
+    ...(err.code ? { code: err.code } : {}),
+    ...(err.errors ? { errors: err.errors } : {}),
+    ...(Number.isInteger(err.revision) ? { revision: err.revision } : {}),
+    ...(err.operationId ? { operationId: err.operationId } : {}),
+    ...(err.hosting !== undefined ? { hosting: err.hosting } : {}),
+    // The agent half's own status, when it refused with an unexpected one.
+    ...(Number.isInteger(err.status) ? { status: err.status } : {}),
+  };
+}
+
 const OperationParamSchema = z.object({
   id: z.string().uuid(),
 });
 
+/**
+ * `digest`: the approval digest that was shown — the installed version's or
+ * a pending update's. `version`: a pending update's version, which approves
+ * that update (with its digest, null when it brings neither relay hooks nor
+ * an agent half).
+ */
 const ApproveHooksBodySchema = z
-  .object({ digest: z.string().regex(/^[a-f0-9]{64}$/, 'digest is a SHA-256 hex string') })
-  .strict();
+  .object({
+    digest: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/, 'digest is a SHA-256 hex string')
+      .nullable()
+      .optional(),
+    version: z
+      .string()
+      .regex(/^[0-9A-Za-z.+-]{1,64}$/, 'version is a plugin version')
+      .optional(),
+  })
+  .strict()
+  .refine((body) => (body.digest ?? null) !== null || body.version !== undefined, {
+    message: 'digest or version is required',
+  });
 
 const AutoApproveBodySchema = z.object({ enabled: z.boolean() }).strict();
 
@@ -281,7 +330,10 @@ export default async function pluginRoutes(fastify, _opts) {
       // `retainedData`: what agents keep of its agent half after it was
       // removed without purge. `hooks`: its lifecycle hooks and their
       // approval (see GET /plugins/:name/hooks).
-      const plugins = await attachHostings(registry.plugins);
+      // `settings`: for a plugin that declares settings, whether it still
+      // needs configuration — { configured, missing, syncedAt }, no values
+      // (see GET /plugins/:name/settings).
+      const plugins = await attachSettingsSummaries(await attachHostings(registry.plugins));
       return {
         plugins: await Promise.all(plugins.map(withHooks)),
         // Every agent's retained data — of uninstalled plugins too, which
@@ -308,7 +360,7 @@ export default async function pluginRoutes(fastify, _opts) {
         return reply.code(404).send({ error: `Plugin "${params.name}" not found` });
       }
 
-      const [withHosting] = await attachHostings([plugin]);
+      const [withHosting] = await attachSettingsSummaries(await attachHostings([plugin]));
       return { plugin: await withHooks(withHosting) };
     },
   );
@@ -538,6 +590,89 @@ export default async function pluginRoutes(fastify, _opts) {
     },
   );
 
+  // ===========================================================================
+  // Settings of an agent-hosted plugin (kept by its agent half)
+  // ===========================================================================
+
+  // ------------------------------------------------------------------
+  // GET /plugins/:name/settings — { schemaVersion, fields, values, configured,
+  // missing, revision, source, syncedAt, hosting }: each non-secret field's
+  // effective value, each secret as { set: true, setAt } or { set: false }
+  // (never a value). Read from the agent half when its hosting is active
+  // and not down (`source: live`), else from the relay's cache (`cache`;
+  // `none` when never read). 404 `no_settings` for a plugin without them.
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/plugins/:name/settings',
+    {
+      preHandler: fastify.requireRole(['admin']),
+    },
+    async (request, reply) => {
+      const params = PluginNameParamSchema.parse(request.params);
+      try {
+        return await getPluginSettingsView(params.name, { logger: request.log });
+      } catch (err) {
+        if (!err.statusCode) {
+          request.log.error(
+            { plugin: params.name, err: err.message },
+            'Failed to read the plugin settings',
+          );
+        }
+        return reply
+          .code(err.statusCode || 500)
+          .send(settingsErrorBody(err, 'Failed to read the plugin settings'));
+      }
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // PUT /plugins/:name/settings { revision, values?, secrets? } — a partial
+  // change (`null` clears an optional field), sent through the tunnel to
+  // the agent half, which stores it: 200 with the settings as above. 400
+  // `errors` (checked here), 409 (`operation_running`, the agent half's
+  // `revision_mismatch` with `revision`, `schema_mismatch`), 422 `errors`
+  // (the agent half's check, normalized), 503 `hosting_offline` with
+  // `hosting`, 502 `settings_unsupported` / `refused` / `unauthenticated`
+  // (an answer without the agent half's responder signature), 504 `timeout`.
+  //
+  // The body may carry secrets. It is handed to the settings library once
+  // and dropped from the request; nothing here logs or repeats it. The
+  // library seals each secret to the one call that carries it through the
+  // tunnel.
+  // ------------------------------------------------------------------
+  fastify.put(
+    '/plugins/:name/settings',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      bodyLimit: AGENT_HALF_SETTINGS_MAX_BYTES,
+      config: { rateLimit: { max: 30, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const body = request.body;
+      request.body = undefined;
+      const params = PluginNameParamSchema.parse(request.params);
+      try {
+        return await updatePluginSettings(params.name, body, {
+          actor: actorFromRequest(request),
+          certSerial: certSerialFromRequest(request),
+          logger: request.log,
+        });
+      } catch (err) {
+        if (!err.statusCode) {
+          // A failure of Lamaste's own (state.db, a malformed hosting record):
+          // its message names no value of the change.
+          request.log.error(
+            { plugin: params.name, err: err.message },
+            'Failed to change the plugin settings',
+          );
+        }
+        return reply
+          .code(err.statusCode || 500)
+          .send(settingsErrorBody(err, 'Failed to change the plugin settings'));
+      }
+    },
+  );
+
   // ===========================================================================
   // Lifecycle hooks: review, approval, auto-approve
   // ===========================================================================
@@ -547,7 +682,8 @@ export default async function pluginRoutes(fastify, _opts) {
   // fail-open flags, effects, digest), the agent hooks, the agent half
   // Lamaste installs (package, version, integrity, service, system
   // packages), the approval (`approval.digest` is what to approve) and a
-  // pending update's relay hook set and agent half
+  // pending update — its relay hook set and agent half, its settings
+  // schema diff, why it waits (`approvalRequired`)
   // ------------------------------------------------------------------
   fastify.get(
     '/plugins/:name/hooks',
@@ -563,10 +699,12 @@ export default async function pluginRoutes(fastify, _opts) {
   );
 
   // ------------------------------------------------------------------
-  // POST /plugins/:name/hooks/approve — approve what the plugin brings
-  // (relay hooks, an agent half Lamaste installs) with the digest that was
-  // shown. Approving a pending update's digest applies the update (202
-  // with its operation).
+  // POST /plugins/:name/hooks/approve { digest?, version? } — approve what
+  // the plugin brings (relay hooks, an agent half Lamaste installs) with
+  // the digest that was shown. Approving a pending update — by its digest,
+  // or by its version (and digest, when it has one) — approves everything
+  // it waits for (`approvalRequired`) and applies it (202 with its
+  // operation).
   // ------------------------------------------------------------------
   fastify.post(
     '/plugins/:name/hooks/approve',
@@ -582,18 +720,23 @@ export default async function pluginRoutes(fastify, _opts) {
       const actor = actorFromRequest(request);
       const certSerial = certSerialFromRequest(request);
       try {
-        const approved = await approveHookSet(plugin, body.digest, {
+        const approved = await approveHookSet(plugin, body.digest ?? null, {
           actor,
           certSerial,
           logger: request.log,
+          version: body.version ?? null,
         });
         if (approved.target === 'update') {
-          const state = await readHookState(plugin.name);
-          const result = await updatePlugin(plugin.name, state.pendingUpdate.version, {
+          // The update as it was approved: fetched again, it must still be that.
+          const result = await updatePlugin(plugin.name, approved.version, {
             actor,
             certSerial,
             logger: request.log,
-            approvedDigest: body.digest,
+            approvedUpdate: {
+              version: approved.version,
+              digest: approved.digest,
+              secretToPlain: approved.secretToPlain,
+            },
             sourceIp: request.ip,
           });
           return reply.code(202).send({ ok: true, ...result });
@@ -603,7 +746,8 @@ export default async function pluginRoutes(fastify, _opts) {
         const statusCode = err.statusCode || 500;
         return reply.code(statusCode).send({
           ...operationErrorBody(err, 'Failed to approve the hook set'),
-          ...(err.currentDigest ? { currentDigest: err.currentDigest } : {}),
+          // The digest to review now: null when what waits brings nothing to approve by one.
+          ...(err.currentDigest !== undefined ? { currentDigest: err.currentDigest } : {}),
         });
       }
     },
@@ -638,9 +782,11 @@ export default async function pluginRoutes(fastify, _opts) {
   // ------------------------------------------------------------------
   // POST /plugins/:name/update { version? } — fetch the version (default
   // latest) and read it without installing it; pin its agent half. A
-  // changed relay hook set or agent half waits for approval
-  // (202 { pendingUpdate }); otherwise the update runs as an operation
-  // (202 { operation }). 200 { upToDate } when there is nothing to do.
+  // changed relay hook set or agent half (unless auto-approved), and a
+  // secret setting turned plain (always), wait for approval
+  // (202 { pendingUpdate }, its `approvalRequired` says why); otherwise the
+  // update runs as an operation (202 { operation }). 200 { upToDate } when
+  // there is nothing to do.
   // ------------------------------------------------------------------
   fastify.post(
     '/plugins/:name/update',
@@ -716,7 +862,8 @@ export default async function pluginRoutes(fastify, _opts) {
           details: { packageName: plugin.packageName, version: plugin.version },
         });
         // `hooks`: the relay hook set to review (and approve) before hosting.
-        return { ok: true, plugin, oidcClients, hooks: await hookStatus(plugin) };
+        const [listed] = await attachSettingsSummaries([plugin]);
+        return { ok: true, plugin: listed, oidcClients, hooks: await hookStatus(plugin) };
       } catch (err) {
         const statusCode = err.statusCode || 500;
         // `route_taken`: another installed plugin holds the route (`route`, `owner`).

package/vendor/serverd/src/routes/management/tunnels.js

@@ -24,11 +24,12 @@ import {
 } from '@lamalibre/lamaste';
 import { getConfig } from '../../lib/config.js';
 import { readTunnels, readSites } from '../../lib/state.js';
-import { loadAgentRegistry } from '../../lib/mtls.js';
+import { getAgentHostFactsHash, loadAgentRegistry } from '../../lib/mtls.js';
 import { getChiselCredentialIssuedAt } from '../../lib/chisel-users.js';
 import { buildChiselArgs } from '../../lib/chisel-args.js';
 import { listAgentPluginAssignments } from '../../lib/plugin-hosting.js';
 import { pendingAgentJobs } from '../../lib/agent-jobs.js';
+import { recordAgentContact } from '../../lib/agent-presence.js';
 import {
   tunnelNginxDeps,
   tunnelCertbotDeps,
@@ -236,6 +237,17 @@ export default async function tunnelRoutes(fastify, _opts) {
       // Parsed outside the try so a malformed ?agent= is a 400 from the
       // shared Zod error handler, not a 500 from the catch below.
       const { agent } = AgentConfigQuerySchema.parse(request.query);
+      // An agent's own call (its sync, every 30 s) is its contact with the
+      // relay — what the panel shows as when a hosting agent last synced.
+      // An admin naming an agent with ?agent= is not that agent's contact.
+      const caller = confinedLabel(request);
+      if (caller !== null && AGENT_LABEL_REGEX.test(caller)) {
+        try {
+          await recordAgentContact(caller);
+        } catch (err) {
+          request.log.warn({ err: err.message, agent: caller }, 'Failed to record agent contact');
+        }
+      }
       try {
         const config = getConfig();
         const tunnels = await readTunnels();
@@ -285,6 +297,14 @@ export default async function tunnelRoutes(fastify, _opts) {
           // through its app host helper (`app-install`, `app-activate`,
           // `app-remove`) — see lib/agent-jobs.js for each job's fields.
           agentJobs: AGENT_LABEL_REGEX.test(label) ? await pendingAgentJobs(label) : [],
+          // For the agent's own sync: the hash of the host facts stored on
+          // its record (null: none), which it compares with its own and
+          // reports them again when they differ — a record replaced since its
+          // last report (enrolled again on the label, a restored backup)
+          // holds none. Not for an admin's ?agent= call.
+          ...(caller !== null && AGENT_LABEL_REGEX.test(caller)
+            ? { hostFactsHash: await getAgentHostFactsHash(caller) }
+            : {}),
         };
       } catch (err) {
         request.log.error(err, 'Failed to generate agent config');