@songsid/agend 2.1.4-beta.5 → 2.1.4-beta.51

package/dist/classic-channel-manager.d.ts

@@ -20,6 +20,8 @@ export interface ClassicChannel {
     instanceName: string;
     backend?: string;
     model?: string;
+    displayName?: string;
+    description?: string;
     autoPauseAfter?: number;
     collab?: boolean;
     preTaskCommand?: string;
@@ -35,6 +37,15 @@ export interface ClassicChannel {
  * the historical name — single-bot users see no change across the upgrade.
  */
 export declare function classicInstanceName(sanitizedName: string, channelId: string, adapterId?: string): string;
+/**
+ * Infer the platform which issued a Classic channel id.
+ *
+ * Telegram group ids are negative. Telegram private-chat ids are positive but
+ * fit in 52 bits (at most 16 decimal digits), while Discord snowflakes are
+ * currently 17-20 decimal digits. Anything else is deliberately left unknown
+ * so custom/future adapters retain the backwards-compatible primary fallback.
+ */
+export declare function inferClassicChannelType(channelId: string): "telegram" | "discord" | undefined;
 /**
  * Manages classic bot channel lifecycle — register/unregister/persist.
  * Persists to ~/.agend/classicBot.yaml with per-channel backend override.
@@ -50,14 +61,26 @@ export declare class ClassicChannelManager {
     private defaults;
     private readonly configPath;
     private lastMtime;
-    /** The primary (channels[0]) adapter id. Legacy entries migrate to it; it also names without a suffix. */
+    /** The primary (channels[0]) adapter id. It names without a suffix. */
     private primaryAdapterId?;
+    /** Config-order adapter identities, used to migrate legacy rows by platform. */
+    private adapters;
     constructor(dataDir: string, logger: Logger);
     /**
-     * Record which adapter is primary. Migrates any legacy (adapterId-less)
-     * entries onto it and rewrites the file in the new format. Idempotent.
+     * Backwards-compatible single-adapter configuration used by tests and older
+     * callers. Production startup supplies the complete adapter list through
+     * {@link configureAdapters} so legacy rows can be matched by platform.
      */
     setPrimaryAdapterId(adapterId: string): void;
+    /**
+     * Configure all adapters in fleet.yaml order, then migrate/repair persisted
+     * Classic registrations. The full list matters when the primary adapter is
+     * a different platform from a legacy channel.
+     */
+    configureAdapters(adapters: ReadonlyArray<{
+        id?: string;
+        type: string;
+    }>): void;
     /** Map key for a (channelId, adapterId) pair. adapterId-less = legacy entry (pre-migration). */
     private compositeKey;
     /** Rebuild the channelId presence set from the entry map (call after any mutation). */
@@ -68,6 +91,16 @@ export declare class ClassicChannelManager {
      * not-yet-migrated legacy entry as a defensive fallback.
      */
     private find;
+    /** Type of a configured adapter id, including historical default ids. */
+    private adapterType;
+    /** Deterministically choose the first configured adapter for a platform. */
+    private adapterForType;
+    /** Preserve the pre-repair file once; instance/workspace data is never deleted. */
+    private backupBeforeAdapterRepair;
+    /**
+     * Load the persisted registry. Returns true when it migrated/repaired data
+     * and the caller should write the normalized registry back to disk.
+     */
     private load;
     private save;
     /** Poll for external file changes (call periodically, e.g. every 30s) */
@@ -85,8 +118,57 @@ export declare class ClassicChannelManager {
     isUserAllowed(userId: string): boolean;
     /** Check if a user is admin. Empty/unset admin_users = no admins (secure default). */
     isAdmin(userId: string): boolean;
+    /**
+     * Grant access to a Discord guild / Telegram group, or promote a user to
+     * ClassicBot admin, and persist. Returns what happened so the caller can say
+     * so rather than claiming a change that did not occur.
+     *
+     * Ids are stored with String(): a Discord snowflake exceeds 2^53 and silently
+     * loses precision as a YAML integer, after which the strict `includes()` in
+     * the isAllowed checks stops matching it.
+     *
+     * "already-open" is not a no-op for tidiness — it is a guard. An empty
+     * allowed_guilds/allowed_groups means allow-all, so writing the FIRST entry
+     * would flip the fleet to an allow-list and lock out every other guild that
+     * works today. The caller asked to allow this one, not to restrict the rest.
+     */
+    private grantTo;
+    /**
+     * Coerce an existing list entry to the string form the isAllowed checks
+     * compare against — but only when that is lossless.
+     *
+     * A YAML number below 2^53 (every Telegram group id) round-trips exactly, so
+     * String() genuinely repairs it. A Discord snowflake does NOT: YAML already
+     * truncated it at parse time (1496407196106494055 arrives as ...494000), so
+     * String() would write a plausible-looking WRONG id back to disk and erase
+     * the one clue that something is broken — that the entry is a number rather
+     * than a quoted string. Leave those untouched and say so; nothing but the
+     * original text can recover the id.
+     */
+    private normalizeId;
+    /**
+     * Report ids YAML has already truncated, at load rather than on first write.
+     *
+     * String comparison in the isAllowed checks recovers an unquoted id below
+     * 2^53, so those need no warning. A Discord snowflake is different: YAML
+     * parsed it into a number that lost its last digits before this code ran, so
+     * no comparison can match it and nothing in the stored value can recover it.
+     * Without this the symptom is a guild that simply never gets in, with no
+     * error anywhere — which is the failure this change exists to remove.
+     */
+    private reportUnquotedIds;
+    /** Allow a Discord guild to use ClassicBot. */
+    allowGuild(guildId: string): "added" | "already" | "already-open";
+    /** Allow a Telegram group to use ClassicBot. */
+    allowGroup(groupId: string): "added" | "already" | "already-open";
+    /** Promote a user to ClassicBot admin (start/stop/model on classic channels). */
+    addAdminUser(userId: string): "added" | "already" | "already-open";
     /** Set the model override for the channel owning `instanceName` and persist. Returns true if found. */
     setModelByInstance(instanceName: string, model: string): boolean;
+    /** Persist agent-selected identity for a Classic instance. */
+    setDisplayNameByInstance(instanceName: string, displayName: string): boolean;
+    /** Persist agent-selected role/description for a Classic instance. */
+    setDescriptionByInstance(instanceName: string, description: string): boolean;
     /** Toggle collab mode for a channel. Returns new state. */
     toggleCollab(channelId: string, adapterId?: string): boolean;
     isCollab(channelId: string, adapterId?: string): boolean;

package/dist/classic-channel-manager.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, readdirSync, unlinkSync, statSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, copyFileSync, readdirSync, unlinkSync, statSync } from "node:fs";
 import { join } from "node:path";
 import yaml from "js-yaml";
 import { getAgendHome } from "./paths.js";
@@ -48,6 +48,26 @@ export function classicInstanceName(sanitizedName, channelId, adapterId) {
     const base = `classic-${sanitizedName}-${suffix}`;
     return adapterId ? `${base}-${sanitizeInstanceName(adapterId)}` : base;
 }
+/**
+ * Infer the platform which issued a Classic channel id.
+ *
+ * Telegram group ids are negative. Telegram private-chat ids are positive but
+ * fit in 52 bits (at most 16 decimal digits), while Discord snowflakes are
+ * currently 17-20 decimal digits. Anything else is deliberately left unknown
+ * so custom/future adapters retain the backwards-compatible primary fallback.
+ */
+export function inferClassicChannelType(channelId) {
+    const value = channelId.trim();
+    if (!/^-?\d+$/.test(value))
+        return undefined;
+    if (value.startsWith("-"))
+        return "telegram";
+    if (value.length >= 17 && value.length <= 20)
+        return "discord";
+    if (value.length >= 1 && value.length <= 16)
+        return "telegram";
+    return undefined;
+}
 /**
  * Manages classic bot channel lifecycle — register/unregister/persist.
  * Persists to ~/.agend/classicBot.yaml with per-channel backend override.
@@ -63,8 +83,10 @@ export class ClassicChannelManager {
     defaults = {};
     configPath;
     lastMtime = 0;
-    /** The primary (channels[0]) adapter id. Legacy entries migrate to it; it also names without a suffix. */
+    /** The primary (channels[0]) adapter id. It names without a suffix. */
     primaryAdapterId;
+    /** Config-order adapter identities, used to migrate legacy rows by platform. */
+    adapters = [];
     constructor(dataDir, logger) {
         this.dataDir = dataDir;
         this.logger = logger;
@@ -72,17 +94,31 @@ export class ClassicChannelManager {
         this.load();
     }
     /**
-     * Record which adapter is primary. Migrates any legacy (adapterId-less)
-     * entries onto it and rewrites the file in the new format. Idempotent.
+     * Backwards-compatible single-adapter configuration used by tests and older
+     * callers. Production startup supplies the complete adapter list through
+     * {@link configureAdapters} so legacy rows can be matched by platform.
      */
     setPrimaryAdapterId(adapterId) {
-        if (this.primaryAdapterId === adapterId)
+        this.configureAdapters([{ id: adapterId, type: adapterId }]);
+    }
+    /**
+     * Configure all adapters in fleet.yaml order, then migrate/repair persisted
+     * Classic registrations. The full list matters when the primary adapter is
+     * a different platform from a legacy channel.
+     */
+    configureAdapters(adapters) {
+        const identities = adapters.map(adapter => ({ id: adapter.id ?? adapter.type, type: adapter.type }));
+        const primaryAdapterId = identities[0]?.id;
+        const unchanged = this.primaryAdapterId === primaryAdapterId
+            && this.adapters.length === identities.length
+            && this.adapters.every((adapter, index) => adapter.id === identities[index]?.id && adapter.type === identities[index]?.type);
+        if (unchanged)
             return;
-        this.primaryAdapterId = adapterId;
-        const hadLegacy = [...this.channels.values()].some(ch => ch.adapterId === undefined);
-        this.load(); // re-derive keys/names now that the primary id is known
-        if (hadLegacy)
-            this.save(); // persist the upgraded format once
+        this.primaryAdapterId = primaryAdapterId;
+        this.adapters = identities;
+        const repaired = this.load();
+        if (repaired && this.backupBeforeAdapterRepair())
+            this.save();
     }
     /** Map key for a (channelId, adapterId) pair. adapterId-less = legacy entry (pre-migration). */
     compositeKey(channelId, adapterId) {
@@ -102,50 +138,172 @@ export class ClassicChannelManager {
         if (exact)
             return exact;
         if (adapterId && adapterId === this.primaryAdapterId) {
-            return this.channels.get(this.compositeKey(channelId, undefined));
+            const legacy = this.channels.get(this.compositeKey(channelId, undefined));
+            if (!legacy)
+                return undefined;
+            const inferredType = inferClassicChannelType(channelId);
+            const primaryType = this.adapterType(adapterId);
+            // A known cross-platform legacy row must wait for its owning adapter to
+            // return; never expose it to the current primary merely as a fallback.
+            if (inferredType && primaryType && inferredType !== primaryType)
+                return undefined;
+            return legacy;
         }
         return undefined;
     }
+    /** Type of a configured adapter id, including historical default ids. */
+    adapterType(adapterId) {
+        if (!adapterId)
+            return undefined;
+        return this.adapters.find(adapter => adapter.id === adapterId)?.type
+            ?? (adapterId === "telegram" || adapterId === "discord" ? adapterId : undefined);
+    }
+    /** Deterministically choose the first configured adapter for a platform. */
+    adapterForType(type) {
+        if (!type)
+            return undefined;
+        const primary = this.adapters.find(adapter => adapter.id === this.primaryAdapterId);
+        if (primary?.type === type)
+            return primary.id;
+        return this.adapters.find(adapter => adapter.type === type)?.id;
+    }
+    /** Preserve the pre-repair file once; instance/workspace data is never deleted. */
+    backupBeforeAdapterRepair() {
+        const backupPath = `${this.configPath}.pre-adapter-repair.bak`;
+        if (existsSync(backupPath) || !existsSync(this.configPath))
+            return true;
+        try {
+            copyFileSync(this.configPath, backupPath);
+            return true;
+        }
+        catch (err) {
+            this.logger.warn({ err, backupPath }, "Failed to back up classicBot.yaml before adapter repair");
+            return false;
+        }
+    }
+    /**
+     * Load the persisted registry. Returns true when it migrated/repaired data
+     * and the caller should write the normalized registry back to disk.
+     */
     load() {
         if (!existsSync(this.configPath))
-            return;
+            return false;
         try {
             const raw = yaml.load(readFileSync(this.configPath, "utf-8"));
             if (!raw)
-                return;
+                return false;
             this.defaults = raw.defaults ?? {};
+            this.reportUnquotedIds();
             this.channels.clear();
+            let repaired = false;
             if (raw.channels) {
+                const loaded = [];
                 for (const [key, val] of Object.entries(raw.channels)) {
                     // Old format: key IS the channelId, no adapterId/instanceName fields.
                     const channelId = val.channelId ?? key;
-                    const adapterId = val.adapterId ?? this.primaryAdapterId; // migrate legacy → primary
+                    const inferredType = inferClassicChannelType(channelId);
+                    const inferredAdapterId = this.adapterForType(inferredType);
+                    // Prefer the adapter whose platform issued the id. Unknown/custom ids
+                    // retain the historical primary fallback.
+                    const adapterId = val.adapterId
+                        ?? (inferredType ? inferredAdapterId : this.primaryAdapterId);
                     const name = val.name ?? channelId;
-                    // Non-primary adapters carry a suffix; primary/legacy keep the historical name.
-                    const suffixAdapter = adapterId && adapterId !== this.primaryAdapterId ? adapterId : undefined;
+                    // An explicit non-primary registration carries a suffix. A legacy
+                    // registration always keeps its historical unsuffixed instance name
+                    // even when platform inference moves it away from channels[0].
+                    const suffixAdapter = val.adapterId && adapterId !== this.primaryAdapterId ? adapterId : undefined;
                     const instanceName = val.instanceName ?? classicInstanceName(sanitizeInstanceName(name), channelId, suffixAdapter);
-                    this.channels.set(this.compositeKey(channelId, adapterId), {
-                        channelId,
-                        adapterId,
-                        name,
-                        instanceName,
-                        backend: val.backend,
-                        model: val.model,
-                        autoPauseAfter: val.auto_pause_after,
-                        collab: val.collab,
-                        preTaskCommand: val.pre_task_command,
-                        contextLines: val.context_lines,
-                        createdAt: val.createdAt ?? "",
-                        createdBy: val.createdBy ?? "",
+                    loaded.push({
+                        persistedAdapterId: val.adapterId,
+                        inferredType,
+                        channel: {
+                            channelId,
+                            adapterId,
+                            name,
+                            instanceName,
+                            backend: val.backend,
+                            model: val.model,
+                            displayName: val.display_name,
+                            description: val.description,
+                            autoPauseAfter: val.auto_pause_after,
+                            collab: val.collab,
+                            preTaskCommand: val.pre_task_command,
+                            contextLines: val.context_lines,
+                            createdAt: val.createdAt ?? "",
+                            createdBy: val.createdBy ?? "",
+                        },
                     });
                 }
+                for (const entry of loaded) {
+                    const { channel, persistedAdapterId, inferredType } = entry;
+                    const inferredAdapterId = this.adapterForType(inferredType);
+                    const persistedType = this.adapterType(persistedAdapterId);
+                    const isLegacy = persistedAdapterId === undefined;
+                    const isCrossPlatformMisbind = !!(persistedAdapterId
+                        && inferredType
+                        && inferredAdapterId
+                        && persistedType
+                        && persistedType !== inferredType);
+                    if (isLegacy && channel.adapterId) {
+                        repaired = true;
+                        this.logger.warn({ channelId: channel.channelId, adapterId: channel.adapterId, instanceName: channel.instanceName, inferredType }, "Migrated legacy Classic channel to inferred adapter");
+                    }
+                    if (isLegacy && inferredType && !channel.adapterId) {
+                        this.logger.warn({ channelId: channel.channelId, inferredType, instanceName: channel.instanceName }, "Classic legacy channel has no configured adapter for its platform; leaving it unbound");
+                    }
+                    if (isCrossPlatformMisbind) {
+                        const correctlyBound = loaded.filter(candidate => candidate !== entry
+                            && candidate.channel.channelId === channel.channelId
+                            && candidate.persistedAdapterId !== undefined
+                            && this.adapterType(candidate.persistedAdapterId) === inferredType);
+                        if (correctlyBound.length > 0) {
+                            // A post-migration /start already created the right registration.
+                            // Keep the live/correct target, drop only the phantom registry row;
+                            // its instance/workspace remains on disk for manual recovery.
+                            repaired = true;
+                            this.logger.warn({
+                                channelId: channel.channelId,
+                                staleAdapterId: persistedAdapterId,
+                                staleInstanceName: channel.instanceName,
+                                activeAdapters: correctlyBound.map(candidate => candidate.persistedAdapterId),
+                                activeInstances: correctlyBound.map(candidate => candidate.channel.instanceName),
+                            }, "Removed phantom Classic channel registration; instance data retained on disk");
+                            continue;
+                        }
+                        channel.adapterId = inferredAdapterId;
+                        repaired = true;
+                        this.logger.warn({
+                            channelId: channel.channelId,
+                            fromAdapterId: persistedAdapterId,
+                            toAdapterId: inferredAdapterId,
+                            instanceName: channel.instanceName,
+                        }, "Repaired cross-platform Classic channel adapter binding");
+                    }
+                    const mapKey = this.compositeKey(channel.channelId, channel.adapterId);
+                    const existing = this.channels.get(mapKey);
+                    if (existing) {
+                        // Malformed/hand-edited duplicates: prefer the already normalized
+                        // explicit row and keep all instance data on disk.
+                        repaired = true;
+                        this.logger.warn({
+                            channelId: channel.channelId,
+                            adapterId: channel.adapterId,
+                            keptInstanceName: existing.instanceName,
+                            ignoredInstanceName: channel.instanceName,
+                        }, "Ignored duplicate Classic channel registration; instance data retained on disk");
+                        continue;
+                    }
+                    this.channels.set(mapKey, channel);
+                }
             }
             this.rebuildChannelIds();
             this.lastMtime = statSync(this.configPath).mtimeMs;
             this.logger.info({ count: this.channels.size }, "Loaded classic channels");
+            return repaired;
         }
         catch (err) {
             this.logger.warn({ err }, "Failed to load classicBot.yaml");
+            return false;
         }
     }
     save() {
@@ -165,6 +323,10 @@ export class ClassicChannelManager {
                 entry.backend = ch.backend;
             if (ch.model)
                 entry.model = ch.model;
+            if (ch.displayName)
+                entry.display_name = ch.displayName;
+            if (ch.description)
+                entry.description = ch.description;
             if (ch.autoPauseAfter !== undefined)
                 entry.auto_pause_after = ch.autoPauseAfter;
             if (ch.contextLines)
@@ -186,12 +348,16 @@ export class ClassicChannelManager {
         if (mtime <= this.lastMtime)
             return false;
         this.logger.info("classicBot.yaml changed — reloading");
-        this.load();
+        const repaired = this.load();
+        if (repaired && this.backupBeforeAdapterRepair())
+            this.save();
         return true;
     }
     /** Reload immediately after an authenticated settings write. */
     reloadFromDisk() {
-        this.load();
+        const repaired = this.load();
+        if (repaired && this.backupBeforeAdapterRepair())
+            this.save();
     }
     getDefaults() { return this.defaults; }
     /** Check if a guild is allowed. Empty/unset/non-array allowed_guilds = allow all (backward compat). */
@@ -199,27 +365,152 @@ export class ClassicChannelManager {
         const list = this.defaults.allowed_guilds;
         if (!Array.isArray(list) || list.length === 0)
             return true;
-        return list.includes(guildId);
+        // String comparison, matching isAdmin. A hand-edited config can hold an
+        // UNQUOTED id, which YAML parses as a number; a strict includes() then
+        // never matches the string an adapter supplies, and the chat is locked out
+        // with no error anywhere. Note this recovers ids below 2^53 only — a
+        // Discord snowflake was already truncated at parse time and no comparison
+        // can restore it, which is why load() reports those instead (see
+        // normalizeId).
+        return list.some(entry => String(entry) === String(guildId));
     }
     /** Check if a Telegram group is allowed. Empty/unset/non-array = allow all. */
     isGroupAllowed(groupId) {
         const list = this.defaults.allowed_groups;
         if (!Array.isArray(list) || list.length === 0)
             return true;
-        return list.includes(groupId);
+        // String comparison, matching isAdmin. A hand-edited config can hold an
+        // UNQUOTED id, which YAML parses as a number; a strict includes() then
+        // never matches the string an adapter supplies, and the chat is locked out
+        // with no error anywhere. Note this recovers ids below 2^53 only — a
+        // Discord snowflake was already truncated at parse time and no comparison
+        // can restore it, which is why load() reports those instead (see
+        // normalizeId).
+        return list.some(entry => String(entry) === String(groupId));
     }
     /** Check if a Telegram user (private chat) is allowed. Empty/unset/non-array = allow all. */
     isUserAllowed(userId) {
         const list = this.defaults.allowed_users;
         if (!Array.isArray(list) || list.length === 0)
             return true;
-        return list.includes(userId);
+        // String comparison, matching isAdmin. A hand-edited config can hold an
+        // UNQUOTED id, which YAML parses as a number; a strict includes() then
+        // never matches the string an adapter supplies, and the chat is locked out
+        // with no error anywhere. Note this recovers ids below 2^53 only — a
+        // Discord snowflake was already truncated at parse time and no comparison
+        // can restore it, which is why load() reports those instead (see
+        // normalizeId).
+        return list.some(entry => String(entry) === String(userId));
     }
     /** Check if a user is admin. Empty/unset admin_users = no admins (secure default). */
     isAdmin(userId) {
         const list = this.defaults.admin_users;
         return !!list && list.length > 0 && list.some(id => String(id) === String(userId));
     }
+    /**
+     * Grant access to a Discord guild / Telegram group, or promote a user to
+     * ClassicBot admin, and persist. Returns what happened so the caller can say
+     * so rather than claiming a change that did not occur.
+     *
+     * Ids are stored with String(): a Discord snowflake exceeds 2^53 and silently
+     * loses precision as a YAML integer, after which the strict `includes()` in
+     * the isAllowed checks stops matching it.
+     *
+     * "already-open" is not a no-op for tidiness — it is a guard. An empty
+     * allowed_guilds/allowed_groups means allow-all, so writing the FIRST entry
+     * would flip the fleet to an allow-list and lock out every other guild that
+     * works today. The caller asked to allow this one, not to restrict the rest.
+     */
+    grantTo(field, id) {
+        const value = String(id);
+        const list = this.defaults[field];
+        // admin_users has no allow-all semantics: empty means nobody is admin.
+        if (field !== "admin_users" && (!Array.isArray(list) || list.length === 0))
+            return "already-open";
+        // A truncated entry can never equal the real id, so this comparison will
+        // not treat it as a duplicate: the correct quoted id is ADDED ALONGSIDE the
+        // broken one, which stays until a human removes it. That is the right
+        // outcome — access starts working immediately, and nothing silently
+        // discards a line the operator wrote.
+        if (Array.isArray(list) && list.some(x => String(x) === value))
+            return "already";
+        // Cast: a preserved out-of-range number stays a number on purpose (see
+        // normalizeId). The isAllowed checks compare with String() either way, so
+        // the runtime contract holds; only the declared type is narrower than what
+        // a hand-edited file can contain.
+        this.defaults[field] = [
+            ...(Array.isArray(list) ? list.map(v => this.normalizeId(field, v)) : []),
+            value,
+        ];
+        this.save();
+        return "added";
+    }
+    /**
+     * Coerce an existing list entry to the string form the isAllowed checks
+     * compare against — but only when that is lossless.
+     *
+     * A YAML number below 2^53 (every Telegram group id) round-trips exactly, so
+     * String() genuinely repairs it. A Discord snowflake does NOT: YAML already
+     * truncated it at parse time (1496407196106494055 arrives as ...494000), so
+     * String() would write a plausible-looking WRONG id back to disk and erase
+     * the one clue that something is broken — that the entry is a number rather
+     * than a quoted string. Leave those untouched and say so; nothing but the
+     * original text can recover the id.
+     */
+    normalizeId(field, value) {
+        if (typeof value !== "number")
+            return value;
+        if (Number.isSafeInteger(value))
+            return String(value);
+        // Preserve silently: reportUnquotedIds() already names this entry once at
+        // load. Logging here too would emit an error on every subsequent write for
+        // a condition the operator has already been told about and cannot fix from
+        // this side.
+        //
+        // Preserving it does NOT keep the original digits: save() re-dumps the
+        // truncated number, so after the first write the file itself shows the
+        // wrong id. Keeping it as a number is still worth doing — that is the only
+        // signal reportUnquotedIds has to find it by — but the file cannot be the
+        // source of the correct value, which is why the error says so.
+        return value;
+    }
+    /**
+     * Report ids YAML has already truncated, at load rather than on first write.
+     *
+     * String comparison in the isAllowed checks recovers an unquoted id below
+     * 2^53, so those need no warning. A Discord snowflake is different: YAML
+     * parsed it into a number that lost its last digits before this code ran, so
+     * no comparison can match it and nothing in the stored value can recover it.
+     * Without this the symptom is a guild that simply never gets in, with no
+     * error anywhere — which is the failure this change exists to remove.
+     */
+    reportUnquotedIds() {
+        for (const field of ["allowed_guilds", "allowed_groups", "allowed_users", "admin_users"]) {
+            const list = this.defaults[field];
+            if (!Array.isArray(list))
+                continue;
+            for (const entry of list) {
+                if (typeof entry === "number" && !Number.isSafeInteger(entry)) {
+                    this.logger.error({ field, value: entry, path: this.configPath }, "classicBot.yaml holds an unquoted id too large for YAML — its precision was lost when the "
+                        + "file was parsed, so it can never match. Re-enter it as a QUOTED string taken from Discord "
+                        + "or Telegram: the digits currently in the file are themselves already wrong, because any "
+                        + "save rewrites this entry from the truncated value. Do not copy it from the file.");
+                }
+            }
+        }
+    }
+    /** Allow a Discord guild to use ClassicBot. */
+    allowGuild(guildId) {
+        return this.grantTo("allowed_guilds", guildId);
+    }
+    /** Allow a Telegram group to use ClassicBot. */
+    allowGroup(groupId) {
+        return this.grantTo("allowed_groups", groupId);
+    }
+    /** Promote a user to ClassicBot admin (start/stop/model on classic channels). */
+    addAdminUser(userId) {
+        return this.grantTo("admin_users", userId);
+    }
     /** Set the model override for the channel owning `instanceName` and persist. Returns true if found. */
     setModelByInstance(instanceName, model) {
         for (const ch of this.channels.values()) {
@@ -231,6 +522,28 @@ export class ClassicChannelManager {
         }
         return false;
     }
+    /** Persist agent-selected identity for a Classic instance. */
+    setDisplayNameByInstance(instanceName, displayName) {
+        for (const ch of this.channels.values()) {
+            if (ch.instanceName === instanceName) {
+                ch.displayName = displayName;
+                this.save();
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Persist agent-selected role/description for a Classic instance. */
+    setDescriptionByInstance(instanceName, description) {
+        for (const ch of this.channels.values()) {
+            if (ch.instanceName === instanceName) {
+                ch.description = description;
+                this.save();
+                return true;
+            }
+        }
+        return false;
+    }
     /** Toggle collab mode for a channel. Returns new state. */
     toggleCollab(channelId, adapterId) {
         const ch = this.find(channelId, adapterId);