dsh-telegram-connector 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.2
+
+- **The Plugins-page configuration page now actually appears and saves.** The
+  three editable fields (`botToken`, `allowedUserIds`, `adminUserId`) are
+  `.volatile()`, so DSH projects the row's settings namespace and passes the
+  `form` object to `plugins.row.config`; without that the Configure page opened
+  with no form. The client bundle now declares the real
+  `@deepseek-ai/dsh-client-ui-plugin-manager` inject, runs every React hook
+  before the loading/unavailable returns, and uses the current
+  `--dsw-alias-*` theme tokens.
+- **Live parameters.** A saved bot token updates the running `TelegramClient`
+  and starts polling if the connector was idle; allowed ids and the admin id
+  are read from the volatile config on every check. The connector now loads
+  with an empty token so the Configure page is reachable, and warns instead of
+  returning early.
+- Tests cover the volatile config shape, the live token path and a rendered
+  ready snapshot.
+
 ## 0.15.1
 
 - Release-check fix: the `0.15.0` tag was cut without its COMPATIBILITY row and

package/COMPATIBILITY.md

@@ -6,7 +6,8 @@ every release.
 
 | Connector | DSH | Status | Notes |
 |---|---|---|---|
-| 0.15.1 | `0.2.1-rc.5` | needs UAT | config page (Plugins → Configure) for bot token, allowed ids and admin id; standalone without the setup updater |
+| 0.15.2 | `0.2.1-rc.5` | needs UAT | config page fixed: volatile fields expose the form, correct client inject, hooks run before loading returns, DSH theme tokens; saving a token starts polling without a reload |
+| 0.15.1 | `0.2.1-rc.5` | previous | config page attempt; the form stayed hidden because the fields were not volatile and the client inject named a package that does not exist |
 | 0.14.1 | `0.2.1-rc.5` | needs UAT | component actions no longer restart the runtime; the tools load on the next start |
 | 0.14.0 | `0.2.1-rc.5` | needs UAT | one command surface: `/menu` card, `/plugins` subcommands, `/components`; aliases and `/man` removed |
 | 0.13.1 | `0.2.1-rc.5` | needs UAT | `/system status` probes the advertised web address, so a LAN-only bind no longer reports loopback as unreachable |

package/README.md

@@ -154,7 +154,7 @@ install without the setup.
 The connector is published to npm as an exact version:
 
 ```sh
-dsh plugin --profile web add dsh-telegram-connector@0.15.1
+dsh plugin --profile web add dsh-telegram-connector@0.15.2
 ```
 
 The registry tarball already contains the built `lib/`, so there is no
@@ -168,7 +168,8 @@ On DSH `0.2.1-rc.5` or newer, open **Plugins** → **dsh-telegram-connector** an
 press **Configure** on the `dsh-telegram-connector` row. The page has three
 fields — **bot token**, **allowed user ids** and **admin user id** — and
 **Save** writes the row's config into the profile's user layer. No `.env` edit
-or restart is needed; the connector recomposes and starts polling.
+or restart is needed; the connector reconnects with a saved token and starts
+polling, and allowed/admin ids are read on each check.
 
 That is the standalone path: the setup is not required, and the connector does
 not assume the setup's supervisor or updater. Commands that need them
@@ -184,7 +185,7 @@ cat >> "$DSH_HOME/profiles/web/pnpm-workspace.yaml" <<'YAML'
 allowBuilds:
   dsh-telegram-connector@https://github.com/vladtsvirko/dsh-telegram-connector.git: true
 YAML
-dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.15.1
+dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.15.2
 ```
 
 That path runs the package's `prepare` build; pnpm ≥ 10 refuses it until the

package/docs/DESIGN.md

@@ -316,7 +316,9 @@ and directories.
   Commit/Roll back, component Enable/Disable/Port, the update card's **Cancel** and Take
   over all check `adminUserId`. The allowlist only decides who may talk to the
   agent; a button that changes the deployment is an admin action.
-- The bot token comes from the environment, never from `cordis.patch.yml`.
+- The bot token comes from the profile's Plugins config (the environment is the
+  fallback), never from `cordis.patch.yml`. The same applies to the allowlist
+  and admin id.
 - The bot is a group admin and can delete topics: `/dangerous cleanup` requires
   an explicit `confirm`, and `/forget` never deletes anything.
 - Plugin mutations are the highest-risk surface: a bundle's code and install

package/docs/STANDALONE.md

@@ -17,7 +17,7 @@ The same package runs in any DSH profile.
 
 ```sh
 # Published package: the tarball already contains lib/, so no build script.
-dsh plugin --profile web add dsh-telegram-connector@0.13.0
+dsh plugin --profile web add dsh-telegram-connector@0.15.2
 ```
 
 From the source repository instead:
@@ -27,11 +27,16 @@ cat >> "$DSH_HOME/profiles/web/pnpm-workspace.yaml" <<'YAML'
 allowBuilds:
   dsh-telegram-connector@https://github.com/vladtsvirko/dsh-telegram-connector.git: true
 YAML
-dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.13.0
+dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.15.2
 ```
 
-The bundle patch mounts the `dsh-telegram-connector` row and reads deployment
-values from the environment:
+Open **Plugins** → **dsh-telegram-connector** → **Configure** and fill in the
+bot token, allowed user ids and optional admin id. **Save** stores them in the
+profile's user layer; a saved token starts polling without a runtime restart,
+and the ids are read on every check. No environment file is required.
+
+The bundle patch still reads deployment values from the environment as the
+fallback:
 
 ```sh
 export DSH_TELEGRAM_BOT_TOKEN='123456:ABC…'

package/lib/client.js

@@ -2,9 +2,9 @@
  * Browser half: the configuration page for the `dsh-telegram-connector` row.
  *
  * DSH's Plugins page declares the `plugins.row.config` slot; this module
- * registers the row's page with the three answers a fresh standalone install
- * needs. The host half already reads the same keys from its Config schema; the
- * patch keeps the environment as the fallback, and a value saved here is the
+ * registers the row's page with the values a fresh standalone install needs.
+ * The host half reads the same volatile keys from its Config schema; the patch
+ * keeps the environment as the fallback, and a value saved here is the
  * profile's user layer, which wins over it.
  */
 window.__ModuleLoader__.load({
@@ -18,67 +18,99 @@ window.__ModuleLoader__.load({
     const h = React.createElement
 
     const KEY = 'dsh-telegram-connector#dsh-telegram-connector'
-    const inputStyle = {
-      boxSizing: 'border-box',
-      width: '100%',
-      padding: '6px 8px',
-      borderRadius: 6,
-      border: '1px solid var(--dsh-border, #d0d5dd)',
-      background: 'var(--dsh-surface, #fff)',
-      color: 'inherit',
-      font: 'inherit',
-    }
+    const styles = `
+.dsh-telegram-form { display: flex; flex-direction: column; gap: 16px; max-width: 560px; color: var(--dsw-alias-label-primary); font-size: 13px; }
+.dsh-telegram-form .panel { display: flex; flex-direction: column; gap: 4px; padding: 10px 12px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 6px; background: var(--dsw-alias-bg-layer-2); }
+.dsh-telegram-form .row { display: flex; align-items: center; gap: 6px; font-weight: 500; }
+.dsh-telegram-form .dot { flex: none; width: 6px; height: 6px; border-radius: 50%; background: var(--dsw-alias-state-idle-primary); }
+.dsh-telegram-form .dot.ok { background: var(--dsw-alias-state-success-primary); }
+.dsh-telegram-form .muted { color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 1.45; }
+.dsh-telegram-form .field { display: flex; flex-direction: column; gap: 6px; }
+.dsh-telegram-form .label { font-weight: 500; }
+.dsh-telegram-form .hint { color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 1.4; }
+.dsh-telegram-form .input { box-sizing: border-box; width: 100%; min-height: 32px; padding: 6px 10px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 6px; background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); font: inherit; font-size: 13px; }
+.dsh-telegram-form .input:focus { outline: 1px solid var(--dsw-alias-brand-primary); outline-offset: 1px; }
+.dsh-telegram-form .input:disabled { opacity: 0.6; }
+.dsh-telegram-form .actions { display: flex; align-items: center; gap: 10px; }
+.dsh-telegram-form .primary { min-height: 32px; padding: 0 14px; border: 1px solid var(--dsw-alias-border-l2); border-radius: 6px; background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); font: inherit; font-size: 13px; font-weight: 500; cursor: pointer; }
+.dsh-telegram-form .primary:hover:not(:disabled) { background: var(--dsw-alias-bg-layer-2); }
+.dsh-telegram-form .primary:disabled { opacity: 0.55; cursor: default; }
+.dsh-telegram-form .message { color: var(--dsw-alias-label-secondary); font-size: 12px; }
+`
 
-    function field(label, hint, input) {
+    function Field({ label, hint, children }) {
       return h(
         'label',
-        { style: { display: 'flex', flexDirection: 'column', gap: 4, marginBottom: 14 } },
-        h('span', { style: { fontWeight: 600 } }, label),
-        hint === undefined ? null : h('span', { style: { opacity: 0.7, fontSize: 12 } }, hint),
-        input,
+        { className: 'field' },
+        h('span', { className: 'label' }, label),
+        hint === undefined ? null : h('span', { className: 'hint' }, hint),
+        children,
       )
     }
 
     function parseIds(text) {
-      return text
-        .split(/[\s,]+/)
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0)
-        .map((part) => Number(part))
-        .filter((id) => Number.isFinite(id) && id > 0)
+      const parts = text.split(/[\s,]+/).map((part) => part.trim()).filter((part) => part.length > 0)
+      const ids = []
+      for (const part of parts) {
+        const id = Number(part)
+        if (!Number.isInteger(id) || id <= 0) return undefined
+        ids.push(id)
+      }
+      return ids
     }
 
     function TelegramConfigForm({ form }) {
-      if (form === undefined) {
-        return h('p', null, 'This plugin does not expose its configuration in this build.')
-      }
-      const state = form.state
-      if (state.status === 'unavailable') {
-        return h('p', null, 'This plugin is not loaded, so it cannot be configured right now.')
-      }
-      if (state.status === 'loading') {
-        return h('p', null, 'Loading the current values…')
-      }
-      const value = state.value ?? {}
+      // Every hook runs before any early return: the page transitions through
+      // loading/unavailable snapshots and a conditional hook would crash React.
+      const state = form === undefined ? undefined : form.state
+      const value = (state === undefined ? undefined : state.value) ?? {}
       const [botToken, setBotToken] = React.useState(String(value.botToken ?? ''))
-      const [allowed, setAllowed] = React.useState(Array.isArray(value.allowedUserIds) ? value.allowedUserIds.join(', ') : '')
-      const [admin, setAdmin] = React.useState(value.adminUserId === undefined ? '' : String(value.adminUserId))
+      const [allowed, setAllowed] = React.useState(
+        Array.isArray(value.allowedUserIds) ? value.allowedUserIds.join(', ') : '',
+      )
+      const [admin, setAdmin] = React.useState(
+        value.adminUserId === undefined ? '' : String(value.adminUserId),
+      )
       const [saving, setSaving] = React.useState(false)
       const [message, setMessage] = React.useState('')
 
+      const revision = state === undefined ? undefined : state.revision
       React.useEffect(() => {
-        const next = state.value ?? {}
+        const next = state === undefined ? {} : (state.value ?? {})
         setBotToken(String(next.botToken ?? ''))
         setAllowed(Array.isArray(next.allowedUserIds) ? next.allowedUserIds.join(', ') : '')
         setAdmin(next.adminUserId === undefined ? '' : String(next.adminUserId))
-      }, [state.revision])
+      }, [revision])
+
+      if (state === undefined) {
+        return h('p', null, 'Loading the configuration…')
+      }
+      if (state.status === 'unavailable') {
+        return h('p', null, 'This plugin is not loaded, so it cannot be configured right now.')
+      }
+      if (state.status === 'loading') {
+        return h('p', null, 'Loading the current values…')
+      }
 
+      const savedToken = String(value.botToken ?? '')
+      const savedAllowed = Array.isArray(value.allowedUserIds) ? value.allowedUserIds : []
+      const savedAdmin = value.adminUserId
+      const tokenSet = savedToken.trim().length > 0
+      const configured = tokenSet && savedAllowed.length > 0
       const disabled = !state.writable || saving
+      const saved = state.user ?? {}
+      const source = (key) => (Object.prototype.hasOwnProperty.call(saved, key) ? 'saved here' : 'environment fallback')
+
       const save = async () => {
         const ids = parseIds(allowed)
-        const adminId = admin.trim().length === 0 ? undefined : Number(admin.trim())
-        if (adminId !== undefined && (!Number.isFinite(adminId) || adminId <= 0)) {
-          setMessage('The admin user id must be a number, or empty to use the first allowed id.')
+        if (ids === undefined) {
+          setMessage('Allowed user ids must be positive integers, separated by commas or spaces.')
+          return
+        }
+        const adminText = admin.trim()
+        const adminId = adminText.length === 0 ? undefined : Number(adminText)
+        if (adminId !== undefined && (!Number.isInteger(adminId) || adminId <= 0)) {
+          setMessage('The admin user id must be a positive integer, or empty to use the first allowed id.')
           return
         }
         setSaving(true)
@@ -92,7 +124,13 @@ window.__ModuleLoader__.load({
               : { op: 'set', path: ['adminUserId'], value: adminId },
           ]
           const ok = await form.mutate(ops, state.revision)
-          setMessage(ok ? 'Saved. The connector reconnects with these values.' : 'The deployment did not accept these values; they were left for you to correct.')
+          if (!ok) {
+            setMessage('The runtime did not accept these values; they were left for you to correct.')
+          } else if (botToken.trim().length === 0 || ids.length === 0) {
+            setMessage('Saved. Set a bot token and at least one allowed user id to start the connector.')
+          } else {
+            setMessage('Saved. The connector uses these values immediately.')
+          }
         } catch (error) {
           setMessage(`Save failed: ${String(error)}`)
         } finally {
@@ -102,58 +140,88 @@ window.__ModuleLoader__.load({
 
       return h(
         'div',
-        null,
-        h('p', null, 'Connect the bot to Telegram. The token comes from @BotFather; user ids are numeric and come from @userinfobot.'),
-        field(
-          'Bot token',
-          'For example 123456789:AA… . Keep it out of screenshots and commits.',
+        { className: 'dsh-telegram-form' },
+        h('style', null, styles),
+        h(
+          'div',
+          { className: 'panel' },
+          h(
+            'div',
+            { className: 'row' },
+            h('span', { className: configured ? 'dot ok' : 'dot' }),
+            h('span', null, configured ? 'Configured' : 'Not configured yet'),
+          ),
+          h(
+            'div',
+            { className: 'muted' },
+            `Bot token ${tokenSet ? 'set' : 'not set'} · ${savedAllowed.length} allowed user(s) · admin ${savedAdmin === undefined ? 'first allowed' : String(savedAdmin)}`,
+          ),
+          h(
+            'div',
+            { className: 'muted' },
+            `Bot token: ${source('botToken')} · allowed ids: ${source('allowedUserIds')} · admin: ${source('adminUserId')}`,
+          ),
+          h('div', { className: 'muted' }, 'Saving writes this profile and applies without restarting the runtime.'),
+        ),
+        h(
+          Field,
+          {
+            label: 'Bot token',
+            hint: 'The token from @BotFather. It is stored in this profile; avoid screenshots and commits.',
+          },
           h('input', {
             type: 'password',
+            className: 'input',
             value: botToken,
             disabled,
-            placeholder: 'the token from @BotFather',
-            style: inputStyle,
+            placeholder: '123456789:AA…',
             onChange: (event) => setBotToken(event.target.value),
           }),
         ),
-        field(
-          'Allowed user ids',
-          'Comma- or space-separated numeric ids. Everyone in this list can talk to the agent and use the sessions.',
+        h(
+          Field,
+          {
+            label: 'Allowed user ids',
+            hint: 'Numeric Telegram ids, comma or space separated. Everyone here can talk to the agent and use its sessions.',
+          },
           h('input', {
             type: 'text',
+            className: 'input',
             value: allowed,
             disabled,
             placeholder: '142283532, 777000111',
-            style: inputStyle,
             onChange: (event) => setAllowed(event.target.value),
           }),
         ),
-        field(
-          'Admin user id',
-          'Optional. One allowed id that may update, restart, roll back and manage plugins; empty uses the first allowed id.',
+        h(
+          Field,
+          {
+            label: 'Admin user id',
+            hint: 'Optional. One allowed id that may update, restart, roll back and manage plugins; empty uses the first allowed id.',
+          },
           h('input', {
             type: 'text',
+            className: 'input',
             value: admin,
             disabled,
             placeholder: 'optional',
-            style: inputStyle,
             onChange: (event) => setAdmin(event.target.value),
           }),
         ),
         h(
           'div',
-          { style: { display: 'flex', alignItems: 'center', gap: 10 } },
+          { className: 'actions' },
           h(
             'button',
             {
               type: 'button',
+              className: 'primary',
               disabled,
               onClick: save,
-              style: { padding: '6px 14px', borderRadius: 6, cursor: disabled ? 'default' : 'pointer' },
             },
             saving ? 'Saving…' : 'Save',
           ),
-          message.length === 0 ? null : h('span', { style: { fontSize: 13 } }, message),
+          message.length === 0 ? null : h('span', { className: 'message' }, message),
         ),
       )
     }

package/lib/index.d.ts

@@ -10,54 +10,35 @@
  *
  * @module dsh-telegram-connector
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
 export declare const name = "dsh-telegram-connector";
 export declare const inject: string[];
-export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
-    botToken: Schema<string, string, "defined">;
-    allowedUserIds: Schema<number[], number[], "defined">;
-    adminUserId: Schema<number, number, "plain">;
-    workspaceRoot: Schema<string, string, "defined">;
-    provider: Schema<string, string, "plain">;
-    model: Schema<string, string, "plain">;
-    editIntervalMs: Schema<number, number, "defined">;
-    pollTimeoutSeconds: Schema<number, number, "defined">;
-    /** Deadline for one Bot API call; a hung call must not freeze a topic. */
-    requestTimeoutSeconds: Schema<number, number, "defined">;
-    downloadTimeoutSeconds: Schema<number, number, "defined">;
-    reconcileIntervalSeconds: Schema<number, number, "defined">;
-    processMode: Schema<"off" | "summary" | "live", "off" | "summary" | "live", "defined">;
-    agentPreset: Schema<string, string, "plain">;
-    reactionsEnabled: Schema<boolean, boolean, "defined">;
-    readReaction: Schema<string, string, "defined">;
-    streamingReaction: Schema<string, string, "defined">;
-    stagedReaction: Schema<string, string, "defined">;
-}>>, Schemastery.ObjectT<NoInfer<{
-    botToken: Schema<string, string, "defined">;
-    allowedUserIds: Schema<number[], number[], "defined">;
-    adminUserId: Schema<number, number, "plain">;
-    workspaceRoot: Schema<string, string, "defined">;
-    provider: Schema<string, string, "plain">;
-    model: Schema<string, string, "plain">;
-    editIntervalMs: Schema<number, number, "defined">;
-    pollTimeoutSeconds: Schema<number, number, "defined">;
-    /** Deadline for one Bot API call; a hung call must not freeze a topic. */
-    requestTimeoutSeconds: Schema<number, number, "defined">;
-    downloadTimeoutSeconds: Schema<number, number, "defined">;
-    reconcileIntervalSeconds: Schema<number, number, "defined">;
-    processMode: Schema<"off" | "summary" | "live", "off" | "summary" | "live", "defined">;
-    agentPreset: Schema<string, string, "plain">;
-    reactionsEnabled: Schema<boolean, boolean, "defined">;
-    readReaction: Schema<string, string, "defined">;
-    streamingReaction: Schema<string, string, "defined">;
-    stagedReaction: Schema<string, string, "defined">;
-}>>, "plain">;
+export interface ConnectorConfigInput {
+    botToken?: string;
+    allowedUserIds?: number[];
+    adminUserId?: number;
+    workspaceRoot?: string;
+    provider?: string;
+    model?: string;
+    editIntervalMs?: number;
+    pollTimeoutSeconds?: number;
+    requestTimeoutSeconds?: number;
+    downloadTimeoutSeconds?: number;
+    reconcileIntervalSeconds?: number;
+    processMode?: 'off' | 'summary' | 'live';
+    agentPreset?: string;
+    reactionsEnabled?: boolean;
+    readReaction?: string;
+    streamingReaction?: string;
+    stagedReaction?: string;
+}
+export declare const Config: Schema<ConnectorConfigInput, ConnectorConfig>;
 export interface ConnectorConfig {
-    botToken: string;
-    allowedUserIds: number[];
+    botToken: Volatile<string>;
+    allowedUserIds: Volatile<number[]>;
     /** The one account that may run update/restart/rollback/plugins commands. */
-    adminUserId?: number;
+    adminUserId: Volatile<number | undefined>;
     workspaceRoot?: string;
     provider?: string;
     model?: string;

package/lib/index.js

@@ -41,9 +41,9 @@ import { bindingsPath, findWorkspace, loadBindings, removeSession, saveBindings,
 export const name = 'dsh-telegram-connector';
 export const inject = ['agents', 'sessions'];
 export const Config = Schema.object({
-    botToken: Schema.string().default(''),
-    allowedUserIds: Schema.array(Schema.number()).default([]),
-    adminUserId: Schema.number(),
+    botToken: Schema.string().default('').volatile(),
+    allowedUserIds: Schema.array(Schema.number()).default([]).volatile(),
+    adminUserId: Schema.number().volatile(),
     workspaceRoot: Schema.string().default(''),
     provider: Schema.string(),
     model: Schema.string(),
@@ -101,9 +101,13 @@ function truncate(text, limit) {
     return clean.length <= limit ? clean : `${clean.slice(0, limit - 1)}…`;
 }
 export function apply(ctx, config) {
-    if (config.botToken.length === 0) {
-        ctx.logger.warn('dsh-telegram-connector: botToken is empty; the connector will not start');
-        return;
+    // The three editable fields are volatile: the Plugins page writes them and
+    // this row reads them through get(). Everything else stays ordinary config.
+    const botToken = () => config.botToken.get();
+    const allowedUserIds = () => config.allowedUserIds.get();
+    const adminUserId = () => config.adminUserId.get();
+    if (botToken().trim().length === 0) {
+        ctx.logger.warn('dsh-telegram-connector: botToken is empty; configure it on the Plugins page');
     }
     const agentPresetService = () => {
         const get = ctx.get;
@@ -112,14 +116,14 @@ export function apply(ctx, config) {
     const requestTimeoutMs = Math.max(5, config.requestTimeoutSeconds ?? 60) * 1000;
     const pollTimeoutMs = Math.max(5, config.pollTimeoutSeconds ?? 25) * 1000 + 30_000;
     const downloadTimeoutMs = Math.max(10, config.downloadTimeoutSeconds ?? 120) * 1000;
-    const client = new TelegramClient(config.botToken, { requestTimeoutMs, pollTimeoutMs, downloadTimeoutMs });
+    const client = new TelegramClient(botToken(), { requestTimeoutMs, pollTimeoutMs, downloadTimeoutMs });
     const agents = ctx.agents;
     // Publisher bots are send-only; the main bot stays the only poller. Tokens come
     // from the environment so they never land in the profile patch.
     const publisherTokens = (process.env.DSH_TELEGRAM_PUBLISHER_TOKENS ?? '')
         .split(/[,\s]+/)
         .map((token) => token.trim())
-        .filter((token) => token.length > 0 && token !== config.botToken);
+        .filter((token) => token.length > 0 && token !== botToken());
     const botHandles = [
         { label: 'main', client, main: true },
         ...publisherTokens.map((token, index) => ({
@@ -155,6 +159,10 @@ export function apply(ctx, config) {
     let bindings = { version: 2, workspaces: {}, sessions: {} };
     let offset = 0;
     let stopped = false;
+    /** True after start() finished its one-time setup. */
+    let started = false;
+    /** True while pollLoop owns getUpdates; a token saved later starts it once. */
+    let polling = false;
     let lastErrorAt = 0;
     let reconcileTimer;
     let reconciling = false;
@@ -169,12 +177,12 @@ export function apply(ctx, config) {
     const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     const updaterToken = process.env.DSH_UPDATER_TOKEN ?? '';
     const updaterUrl = (process.env.DSH_UPDATER_URL ?? 'http://updater:8787').replace(/\/+$/, '');
-    if (config.allowedUserIds.length === 0) {
+    if (allowedUserIds().length === 0) {
         logger.warn('dsh-telegram-connector: allowedUserIds is empty; every message will be refused');
     }
     /** Last error an agent reported, shown by `/system status`. */
     let lastAgentError;
-    const isAllowed = (userId) => userId !== undefined && config.allowedUserIds.includes(userId);
+    const isAllowed = (userId) => userId !== undefined && allowedUserIds().includes(userId);
     /**
      * Who may run profile-global commands (update, restart, rollback, plugins).
      *
@@ -185,8 +193,8 @@ export function apply(ctx, config) {
     const isAdmin = (userId) => {
         if (userId === undefined)
             return false;
-        if (config.adminUserId !== undefined)
-            return userId === config.adminUserId;
+        if (adminUserId() !== undefined)
+            return userId === adminUserId();
         // No admin configured (an upgraded deployment, or one set up by hand): the
         // owner of the control chat is the admin, so an upgrade cannot lock anyone
         // out. In a private chat the chat id *is* the user id.
@@ -202,9 +210,9 @@ export function apply(ctx, config) {
         const sender = message.from?.id;
         if (isAdmin(sender))
             return true;
-        const who = config.adminUserId === undefined
+        const who = adminUserId() === undefined
             ? 'the owner of this chat (`DSH_ADMIN_USER_ID` is not set)'
-            : `admin ${String(config.adminUserId)}`;
+            : `admin ${String(adminUserId())}`;
         void reply(message, `only ${who} can do that — it changes the deployment for everyone.`);
         return false;
     };
@@ -1604,11 +1612,11 @@ export function apply(ctx, config) {
         ].join('\n'));
     };
     /** Who may run profile-global commands, and how that was decided. */
-    const adminLine = () => config.adminUserId === undefined
+    const adminLine = () => adminUserId() === undefined
         ? bindings.controlChatId === undefined
             ? 'admin: any allowed user until the bot chat is used (set `DSH_ADMIN_USER_ID` to name one)'
             : 'admin: the owner of this chat (set `DSH_ADMIN_USER_ID` to name one explicitly)'
-        : `admin: ${String(config.adminUserId)}`;
+        : `admin: ${String(adminUserId())}`;
     /** The provider key this deployment is supposed to have. */
     const providerKeyNames = () => {
         const declared = (process.env.DSH_PROVIDER_API_KEY_ENV ?? '').trim();
@@ -5284,6 +5292,14 @@ export function apply(ctx, config) {
                 stderr(`${bot.label}: member of ${stats.present}/${total} bound group(s)`);
         }
     };
+    const ensurePolling = () => {
+        if (!started || polling || stopped || botToken().trim().length === 0)
+            return;
+        polling = true;
+        void pollLoop().finally(() => {
+            polling = false;
+        });
+    };
     const start = async () => {
         // A file that could not be read is set aside by the loader; say so in the
         // chat, once, instead of letting the bot answer "not attached" forever.
@@ -5353,7 +5369,13 @@ export function apply(ctx, config) {
             await sendTo(chat, 0, `the runtime's workspace registry did not list ${String(healed.restored)} workspace(s) / ${String(healed.attached)} session(s) that Telegram still had — they are back, and the web UI lists them again.`, 'control');
         })
             .catch((error) => stderr(`registry repair failed: ${String(error)}`));
-        void pollLoop();
+        started = true;
+        if (botToken().trim().length === 0) {
+            stderr('not configured: set the bot token on the Plugins page; polling starts when it is saved');
+        }
+        else {
+            ensurePolling();
+        }
         void announceTrial();
         void flushBridgeTurns().catch((error) => stderr(`bridge flush failed: ${String(error)}`));
         void replayBridgeInputs().catch((error) => stderr(`bridge replay failed: ${String(error)}`));
@@ -5732,6 +5754,22 @@ export function apply(ctx, config) {
             return;
         }
     });
+    // A volatile-only config commit updates the running fiber in place; it does
+    // not reload this plugin. Follow the values that affect the long-lived bot:
+    // a new token changes the client and starts polling if it was idle.
+    ctx.on('loader/volatile-update', (paths) => {
+        const touched = (field) => paths.some((path) => path[path.length - 1] === field);
+        if (touched('botToken')) {
+            const next = botToken().trim();
+            client.setToken(next);
+            stderr(next.length > 0 ? 'bot token updated; polling with the new token' : 'bot token cleared; polling will fail until one is set');
+            ensurePolling();
+        }
+        if (touched('allowedUserIds'))
+            stderr(`allowed users updated (${String(allowedUserIds().length)})`);
+        if (touched('adminUserId'))
+            stderr(`admin updated (${adminUserId() === undefined ? 'first allowed user' : String(adminUserId())})`);
+    });
     ctx.effect(() => {
         void start();
         return () => {