@songsid/agend 2.2.0-alpha.2 → 2.2.0-alpha.4

package/dist/quickstart-api.d.ts

@@ -53,10 +53,35 @@ export interface WizardEnvironment {
         allowed_users?: string[];
     }>;
     has_fleet: boolean;
+    /** #1519 P7: the agents already configured — the wizard offers to connect one instead of overwriting it. */
+    agents?: Array<{
+        name: string;
+        working_directory: string | null;
+        backend: string | null;
+    }>;
 }
 export interface WizardPlanInput {
     platform: "telegram" | "discord";
+    /**
+     * The env var for the token. A plan without one gets a generated name (#1519 P1: `AGEND_<PLATFORM>_<ID>_TOKEN`,
+     * unique); the commit always carries it — the plan's — so what an admin confirms is what is written.
+     */
     token_env: string;
+    /** #1519 P1: "New connection" — add the connection only; no agent is written. */
+    connection_only?: boolean;
+    /**
+     * #1519 P7: `instance_name` is an agent that already exists — bind it to the new connection and leave its directory
+     * and backend as they are. Without it, an existing name is refused: the wizard never overwrites an agent.
+     */
+    existing_agent?: boolean;
+    /** The new connection's id; free ids only (a new connection never takes over one). Default: the platform's, else numbered. */
+    channel_id?: string;
+    /**
+     * The token env came from a plan (#1529 review): the commit then re-checks, under its write lease, that the name is
+     * still free of everything the plan avoided — a generated name never overwrites a value. Without it, the name is the
+     * caller's own (the pre-fleet setup form, the CLI) and only another connection's or a reserved name is refused.
+     */
+    token_env_generated?: boolean;
     backend: string;
     working_directory: string;
     instance_name: string;
@@ -69,28 +94,71 @@ export interface WizardPlanInput {
 export interface WizardPlan {
     /** The channel entry that will be merged into fleet.yaml. */
     channel: Record<string, unknown>;
+    /**
+     * `topic`: an existing agent whose topic belongs to another chat (#1549 review) — `from` its old id, `to` the id it
+     * gets here (the General topic of the new chat, for a General agent) or null (none: the old one is not carried).
+     */
     instance: {
         name: string;
         working_directory: string;
         backend: string;
-    };
+        channel_id: string;
+        existing?: boolean;
+        topic?: {
+            from: string;
+            to: string | null;
+        };
+    } | null;
+    /** The new connection's id and the env var its token goes to. */
+    channel_id: string;
+    token_env: string;
     /** Env var names only — never the value. */
     env_keys: string[];
     warnings: string[];
 }
 /**
- * A channel id that is free, or the id of the connection being replaced.
- *
- * The platform name is the obvious id and the first bot gets it. A second bot on
- * the same platform cannot have it — `duplicate channel id` — so it is
- * qualified by the variable that holds its token. Without this the wizard can
- * never add a second Telegram bot at all.
+ * A free channel id for a NEW connection (#1519 P1, S1: the wizard never takes over an existing connection). The
+ * platform name is the obvious id and the first bot gets it; the next one on that platform is `<platform>-2`, and so on.
  */
-export declare function nextChannelId(platform: string, tokenEnv: string, existing: ReadonlyArray<{
+export declare function nextChannelId(platform: string, existing: ReadonlyArray<{
     id: string;
-    token_env: string | null;
 }>): string;
-export declare function planQuickstart(input: WizardPlanInput, env: WizardEnvironment): WizardPlan;
+/**
+ * #1519 P7: why the agent part of this input cannot be written, or null. A new agent's name must be free (the wizard
+ * never overwrites one); an existing agent must exist. A connection-only input has no agent part.
+ */
+export declare function agentConflict(input: Pick<WizardPlanInput, "instance_name" | "existing_agent" | "connection_only">, cfg: FleetConfig | null): string | null;
+/**
+ * #1519 P7: an existing agent's input as the plan shows it — with the agent's own directory and backend (the wizard does
+ * not ask for them, and they are not changed). Any other input as it is.
+ */
+export declare function withExistingAgent<T extends Pick<WizardPlanInput, "instance_name" | "existing_agent" | "working_directory" | "backend">>(input: T, cfg: FleetConfig | null): T;
+/**
+ * #1549 review: a topic id means something only in its chat (a Telegram group's forum topic, a Discord server's
+ * channel). An existing agent moved to a connection in another chat would keep an id that, there, is some other topic —
+ * or none yet — and inbound messages from that topic would route to it. So its topic binding goes with the move unless
+ * the new connection is in the same chat (same platform and group/server). Unknown (the old connection cannot be
+ * found) is not "the same": the binding goes.
+ */
+export declare function releasesTopic(cfg: FleetConfig, instanceName: string, newChannel: {
+    type?: unknown;
+    group_id?: unknown;
+}): boolean;
+/**
+ * The topic an existing agent has after moving to `newChannel`: its own when the chat is the same; else, for the
+ * General agent, the new chat's General (Telegram's thread 1, the Discord connection's general channel); else none.
+ */
+export declare function movedTopic(cfg: FleetConfig, instanceName: string, newChannel: Record<string, unknown>): {
+    from: string;
+    to: string | number | null;
+} | null;
+/** The plan as the wizard shows it: an existing agent's topic that the move changes is said so. */
+export declare function withTopicRelease(plan: WizardPlan, cfg: FleetConfig, input: Pick<WizardPlanInput, "instance_name" | "existing_agent">): WizardPlan;
+/** Why this input cannot be a new connection, or null: a taken id or token env (it would replace a connection). */
+export declare function newConnectionConflict(input: Pick<WizardPlanInput, "token_env" | "channel_id">, env: Pick<WizardEnvironment, "channels">): string | null;
+export declare function planQuickstart(input: WizardPlanInput, env: WizardEnvironment & {
+    taken_env?: ReadonlySet<string>;
+}): WizardPlan;
 /** Upsert one `KEY=value` line, preserving everything else in the file. */
 export declare function upsertEnvLine(existing: string, key: string, value: string): string;
 export declare function writeQuickstartSecret(dataDir: string, key: string, value: string): SecretWriteResult;
@@ -101,6 +169,10 @@ export type ProbeRequest = {
 } | {
     action: "guilds";
     token: string;
+} | {
+    action: "channels";
+    token: string;
+    guild_id: string;
 } | {
     action: "await-telegram-start";
     token: string;
@@ -109,6 +181,14 @@ export type ProbeRequest = {
 export type ProbeResult = {
     ok: true;
     identity: BotIdentity;
+    invite_url?: string;
+    portal_url?: string;
+} | {
+    ok: true;
+    channels: Array<{
+        id: string;
+        name: string;
+    }>;
 } | {
     ok: true;
     guilds: DiscordGuild[];
@@ -137,15 +217,6 @@ export declare function runProviderProbe(request: ProbeRequest, opts?: {
     deadlineMs?: number;
 }): Promise<ProbeResult>;
 export declare function detectWizardBackends(): string[];
-/**
- * What the wizard's routes need from their host.
- *
- * Five fields, and none of them is a fleet: this is the whole "ConfigVerbs +
- * ProviderProbeVerbs" surface. A running fleet supplies it from FleetManager; a
- * pre-fleet setup host supplies it from a file. `tests/prefleet-host.test.ts`
- * asserts this module's import graph reaches neither fleet-manager, daemon nor
- * instance-lifecycle, so the host cannot grow a path to them by accident.
- */
 /** One pure draft shared by the writer and the authoritative confirmation diff. */
 export declare function draftQuickstart(cfg: FleetConfig, body: WizardPlanInput, plan: WizardPlan): FleetConfig;
 export interface QuickstartApiContext {
@@ -166,6 +237,8 @@ export interface QuickstartApiContext {
 /** The channels as the wizard sees them, from either config shape. */
 export declare function wizardChannels(cfg: FleetConfig | null): WizardEnvironment["channels"];
 /** Reject anything that would land in fleet.yaml or a shell env file unchecked. */
-export declare function validateWizardInput(input: Partial<WizardPlanInput>): string | null;
+export declare function validateWizardInput(input: Partial<WizardPlanInput>, opts?: {
+    tokenEnvOptional?: boolean;
+}): string | null;
 /** Handle one wizard route. Returns false when the path is not one of ours. */
 export declare function handleQuickstartRequest(req: IncomingMessage, res: ServerResponse, url: URL, ctx: QuickstartApiContext): boolean;

package/dist/quickstart-api.js

@@ -2,10 +2,13 @@ import { settingsRequestExecution, settingsWrite } from "./settings-request-capa
 import { SettingsExecutionError, settingsFileResource, trySettingsLease } from "./settings-transaction.js";
 import { readBoundedWebBody } from "./web-body.js";
 import { permitWebContinuation } from "./web-continuation.js";
+import { gatewayRequestContext } from "./web-request-context.js";
 import { join } from "node:path";
 import { SecretStore } from "./secret-store.js";
+import { discordBotPortalUrl, discordInviteUrl } from "./discord-permissions.js";
+import { EnvFileUnreadableError, envFileKeys, generateTokenEnvName, generatedTokenEnvStale, newTokenEnvConflict, takenTokenEnvNames, TOKEN_ENV_PATTERN } from "./token-env-name.js";
 import { KNOWN_BACKENDS, validateFleetConfig } from "./config-validator.js";
-import { awaitTelegramGroupStart, detectInstalledBackends, listDiscordGuilds, TelegramPollConflictError, verifyDiscordToken, verifyTelegramToken, } from "./provider-probe.js";
+import { awaitTelegramGroupStart, detectInstalledBackends, listDiscordGuilds, listDiscordTextChannels, TelegramPollConflictError, verifyDiscordToken, verifyTelegramToken, } from "./provider-probe.js";
 /** One slice of Telegram long polling, so the browser gets an answer. */
 export const TELEGRAM_WAIT_SLICE_MS = 25_000;
 export const WIZARD_BACKENDS = [
@@ -18,34 +21,98 @@ export const WIZARD_BACKENDS = [
     { name: "muse", binary: "muse" },
 ];
 /**
- * A channel id that is free, or the id of the connection being replaced.
- *
- * The platform name is the obvious id and the first bot gets it. A second bot on
- * the same platform cannot have it — `duplicate channel id` — so it is
- * qualified by the variable that holds its token. Without this the wizard can
- * never add a second Telegram bot at all.
+ * A free channel id for a NEW connection (#1519 P1, S1: the wizard never takes over an existing connection). The
+ * platform name is the obvious id and the first bot gets it; the next one on that platform is `<platform>-2`, and so on.
  */
-export function nextChannelId(platform, tokenEnv, existing) {
-    const owner = existing.find(channel => channel.token_env === tokenEnv);
-    if (owner)
-        return owner.id;
+export function nextChannelId(platform, existing) {
     const taken = new Set(existing.map(channel => channel.id));
     if (!taken.has(platform))
         return platform;
-    const qualified = `${platform}-${tokenEnv.toLowerCase()}`;
-    if (!taken.has(qualified))
-        return qualified;
     for (let n = 2;; n++) {
-        const candidate = `${qualified}-${n}`;
+        const candidate = `${platform}-${n}`;
         if (!taken.has(candidate))
             return candidate;
     }
 }
+/**
+ * #1519 P7: why the agent part of this input cannot be written, or null. A new agent's name must be free (the wizard
+ * never overwrites one); an existing agent must exist. A connection-only input has no agent part.
+ */
+export function agentConflict(input, cfg) {
+    if (input.connection_only)
+        return null;
+    const exists = !!cfg && Object.hasOwn(cfg.instances ?? {}, input.instance_name);
+    if (input.existing_agent)
+        return exists ? null : `there is no agent called "${input.instance_name}"`;
+    return exists ? `an agent called "${input.instance_name}" already exists — connect it as an existing agent, or choose another name` : null;
+}
+/**
+ * #1519 P7: an existing agent's input as the plan shows it — with the agent's own directory and backend (the wizard does
+ * not ask for them, and they are not changed). Any other input as it is.
+ */
+export function withExistingAgent(input, cfg) {
+    if (!input.existing_agent || !cfg || !Object.hasOwn(cfg.instances ?? {}, input.instance_name))
+        return input;
+    const inst = cfg.instances[input.instance_name];
+    return { ...input, working_directory: inst.working_directory ?? "", backend: inst.backend ?? cfg.defaults?.backend ?? "claude-code" };
+}
+/**
+ * #1549 review: a topic id means something only in its chat (a Telegram group's forum topic, a Discord server's
+ * channel). An existing agent moved to a connection in another chat would keep an id that, there, is some other topic —
+ * or none yet — and inbound messages from that topic would route to it. So its topic binding goes with the move unless
+ * the new connection is in the same chat (same platform and group/server). Unknown (the old connection cannot be
+ * found) is not "the same": the binding goes.
+ */
+export function releasesTopic(cfg, instanceName, newChannel) {
+    if (!Object.hasOwn(cfg.instances ?? {}, instanceName))
+        return false;
+    const inst = cfg.instances[instanceName];
+    if (inst.topic_id === undefined || inst.topic_id === null || inst.topic_id === "")
+        return false;
+    const channels = wizardChannels(cfg);
+    const old = inst.channel_id != null ? channels.find(c => c.id === String(inst.channel_id)) : channels[0];
+    if (!old || old.group_id == null || newChannel.group_id == null)
+        return true;
+    return !(old.type === String(newChannel.type ?? "") && old.group_id === String(newChannel.group_id));
+}
+/**
+ * The topic an existing agent has after moving to `newChannel`: its own when the chat is the same; else, for the
+ * General agent, the new chat's General (Telegram's thread 1, the Discord connection's general channel); else none.
+ */
+export function movedTopic(cfg, instanceName, newChannel) {
+    if (!releasesTopic(cfg, instanceName, newChannel))
+        return null;
+    const inst = cfg.instances[instanceName];
+    const from = String(inst.topic_id);
+    if (inst.general_topic !== true)
+        return { from, to: null };
+    if (newChannel.type === "telegram")
+        return { from, to: 1 };
+    const general = newChannel.general_channel_id;
+    return { from, to: general != null && /^\d{17,}$/.test(String(general)) ? String(general) : null };
+}
+/** The plan as the wizard shows it: an existing agent's topic that the move changes is said so. */
+export function withTopicRelease(plan, cfg, input) {
+    const moved = input.existing_agent && plan.instance ? movedTopic(cfg, input.instance_name, plan.channel) : null;
+    if (!moved || !plan.instance)
+        return plan;
+    return { ...plan, instance: { ...plan.instance, topic: { from: moved.from, to: moved.to == null ? null : String(moved.to) } } };
+}
+/** Why this input cannot be a new connection, or null: a taken id or token env (it would replace a connection). */
+export function newConnectionConflict(input, env) {
+    if (input.channel_id && env.channels.some(channel => channel.id === input.channel_id)) {
+        return `a connection called "${input.channel_id}" already exists — a new connection never replaces one`;
+    }
+    return input.token_env ? newTokenEnvConflict(input.token_env, env.channels) : null;
+}
 export function planQuickstart(input, env) {
     const warnings = [];
+    const channelId = input.channel_id || nextChannelId(input.platform, env.channels);
+    const tokenEnv = input.token_env || generateTokenEnvName(input.platform, channelId, env.taken_env ?? takenTokenEnvNames({ channelEnvs: env.channels.map(channel => channel.token_env) }));
     const channel = {
+        id: channelId,
         type: input.platform,
-        bot_token_env: input.token_env,
+        bot_token_env: tokenEnv,
         mode: "topic",
         access: { mode: "locked", allowed_users: input.admin_user_id ? [input.admin_user_id] : [] },
     };
@@ -53,8 +120,11 @@ export function planQuickstart(input, env) {
     if (input.platform === "discord") {
         if (input.guild_id)
             channel.group_id = input.guild_id;
+        // Write general_channel_id under options (the runtime reads it from there).
+        // Top-level general_channel_id was a bug introduced in c25045b0; old files
+        // that still have it at the top level are handled by discordGeneralChannelId().
         if (input.general_channel_id)
-            channel.general_channel_id = input.general_channel_id;
+            channel.options = { ...(channel.options ?? {}), general_channel_id: input.general_channel_id };
     }
     else if (input.group_id) {
         channel.group_id = input.group_id;
@@ -62,25 +132,17 @@ export function planQuickstart(input, env) {
     if (!input.admin_user_id) {
         warnings.push("No admin user id: access stays locked with an empty allow list, so nobody can drive the bot until you add one.");
     }
-    const clash = env.channels.find(existing => existing.token_env === input.token_env);
-    if (clash) {
-        warnings.push(`${input.token_env} is already used by the "${clash.id}" connection — its token will be overwritten.`);
-        // Re-running the wizard rewrites that connection's access block, so anyone
-        // else on its allow list stops being able to drive the bot. That is a
-        // lockout, and it must not happen without the user reading it first.
-        const previous = clash.allowed_users ?? [];
-        const dropped = previous.filter(user => user !== input.admin_user_id);
-        if (dropped.length) {
-            warnings.push(`Its allow list is replaced: ${dropped.join(", ")} will no longer be able to use the bot.`);
-        }
-    }
-    if (!env.backends.includes(input.backend)) {
+    if (!input.connection_only && !input.existing_agent && !env.backends.includes(input.backend)) {
         warnings.push(`${input.backend} was not found on this host; the agent will fail to start until it is installed.`);
     }
     return {
         channel,
-        instance: { name: input.instance_name, working_directory: input.working_directory, backend: input.backend },
-        env_keys: [input.token_env],
+        // The agent is the new connection's (#1529 review): bound to it, not to whichever connection is first.
+        instance: input.connection_only ? null : { name: input.instance_name, working_directory: input.working_directory, backend: input.backend, channel_id: channelId,
+            ...(input.existing_agent ? { existing: true } : {}) },
+        channel_id: channelId,
+        token_env: tokenEnv,
+        env_keys: [tokenEnv],
         warnings,
     };
 }
@@ -120,11 +182,19 @@ export async function runProviderProbe(request, opts = {}) {
         const identity = request.platform === "discord"
             ? await verifyDiscordToken(request.token)
             : await verifyTelegramToken(request.token);
+        // #1519 P3: a verified Discord bot comes with its invite (the one permission set) and its portal page.
+        if (request.platform === "discord" && identity.valid && identity.id) {
+            return { ok: true, identity, invite_url: discordInviteUrl(identity.id), portal_url: discordBotPortalUrl(identity.id) };
+        }
         return { ok: true, identity };
     }
     if (request.action === "guilds") {
         return { ok: true, guilds: await listDiscordGuilds(request.token) };
     }
+    if (request.action === "channels") {
+        const listed = await listDiscordTextChannels(request.token, request.guild_id);
+        return listed.ok ? { ok: true, channels: listed.channels } : { ok: false, error: listed.error };
+    }
     if (opts.isTokenInUse?.(request.token)) {
         return {
             ok: false,
@@ -159,22 +229,31 @@ export function detectWizardBackends() {
  * asserts this module's import graph reaches neither fleet-manager, daemon nor
  * instance-lifecycle, so the host cannot grow a path to them by accident.
  */
+function withMovedTopic(inst, moved) {
+    if (!moved)
+        return inst;
+    const { topic_id: _old, ...rest } = inst;
+    return (moved.to == null ? rest : { ...rest, topic_id: moved.to });
+}
 /** One pure draft shared by the writer and the authoritative confirmation diff. */
 export function draftQuickstart(cfg, body, plan) {
     const draft = structuredClone(cfg), summary = wizardChannels(cfg);
     const channels = draft.channels ?? (draft.channel ? [draft.channel] : []);
-    const existingIndex = channels.findIndex(channel => channel.bot_token_env === body.token_env);
-    const entry = { id: nextChannelId(body.platform, body.token_env, summary), ...plan.channel };
-    if (existingIndex >= 0)
-        channels[existingIndex] = { ...channels[existingIndex], ...entry };
-    else
-        channels.push(entry);
+    // Always a new connection (#1519 P1, S1): never matched to one by token env, platform or group. The commit refuses a
+    // taken id or env before it gets here (newConnectionConflict).
+    void summary;
+    channels.push({ ...plan.channel });
     draft.channels = channels;
     delete draft.channel;
-    draft.instances = { ...draft.instances, [body.instance_name]: {
-            ...(Object.hasOwn(draft.instances, body.instance_name) ? draft.instances[body.instance_name] : {}),
-            working_directory: body.working_directory, backend: body.backend,
-        } };
+    if (body.connection_only)
+        return draft;
+    const existing = Object.hasOwn(draft.instances, body.instance_name) ? draft.instances[body.instance_name] : undefined;
+    draft.instances = { ...draft.instances, [body.instance_name]: body.existing_agent && existing
+            // #1519 P7: an existing agent keeps everything it has; only its connection becomes the new one — and a topic of
+            // another chat is not carried into this one (#1549 review: releasesTopic).
+            ? withMovedTopic({ ...existing, channel_id: plan.channel_id }, movedTopic(cfg, body.instance_name, plan.channel))
+            : { ...(existing ?? {}), working_directory: body.working_directory, backend: body.backend, channel_id: plan.channel_id },
+    };
     return draft;
 }
 function json(res, status, data) {
@@ -197,17 +276,30 @@ export function wizardChannels(cfg) {
     }));
 }
 /** Reject anything that would land in fleet.yaml or a shell env file unchecked. */
-export function validateWizardInput(input) {
+export function validateWizardInput(input, opts = {}) {
     if (input.platform !== "telegram" && input.platform !== "discord")
         return "platform must be telegram or discord";
-    if (!input.token_env || !/^[A-Z][A-Z0-9_]{2,63}$/.test(input.token_env))
+    if (input.connection_only !== undefined && typeof input.connection_only !== "boolean")
+        return "connection_only must be a boolean";
+    if (input.existing_agent !== undefined && typeof input.existing_agent !== "boolean")
+        return "existing_agent must be a boolean";
+    if (input.token_env_generated !== undefined && typeof input.token_env_generated !== "boolean")
+        return "token_env_generated must be a boolean";
+    if (!(opts.tokenEnvOptional && input.token_env === undefined) && (!input.token_env || !TOKEN_ENV_PATTERN.test(input.token_env)))
         return "token_env must be an UPPER_SNAKE env var name";
-    if (!input.backend || !KNOWN_BACKENDS.includes(input.backend))
-        return "backend must be a known backend";
-    if (!input.working_directory || !input.working_directory.startsWith("/"))
-        return "working_directory must be an absolute path";
-    if (!input.instance_name || !/^[A-Za-z0-9._-]{1,128}$/.test(input.instance_name))
-        return "instance_name must be [A-Za-z0-9._-]";
+    if (input.channel_id !== undefined && (typeof input.channel_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/.test(input.channel_id)))
+        return "channel_id must be [A-Za-z0-9_-], up to 32 characters";
+    if (!input.connection_only) {
+        if (!input.instance_name || !/^[A-Za-z0-9._-]{1,128}$/.test(input.instance_name))
+            return "instance_name must be [A-Za-z0-9._-]";
+        // An existing agent keeps its own directory and backend: neither is asked for.
+        if (!input.existing_agent) {
+            if (!input.backend || !KNOWN_BACKENDS.includes(input.backend))
+                return "backend must be a known backend";
+            if (!input.working_directory || !input.working_directory.startsWith("/"))
+                return "working_directory must be an absolute path";
+        }
+    }
     for (const [field, value] of Object.entries({
         group_id: input.group_id, guild_id: input.guild_id,
         general_channel_id: input.general_channel_id, admin_user_id: input.admin_user_id,
@@ -229,10 +321,17 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             backends: detectWizardBackends(),
             has_fleet: !!cfg && Object.keys(cfg.instances ?? {}).length > 0,
             channels: wizardChannels(cfg),
+            agents: Object.entries(cfg?.instances ?? {}).map(([name, inst]) => ({
+                name, working_directory: inst.working_directory ?? null, backend: inst.backend ?? null
+            })),
         });
         return true;
     }
     if (method === "POST" && path === "/api/settings/quickstart/probe") {
+        if (gatewayRequestContext(req)) {
+            json(res, 403, { error: "Token verification is not permitted over a public link" });
+            return true;
+        }
         readBody(req, 16 * 1024).then(async (buf) => {
             if (!permitWebContinuation(req, res, ctx))
                 return;
@@ -247,14 +346,14 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             if (!token)
                 return json(res, 400, { error: "token required" });
             const action = String(body.action ?? "");
-            if (action !== "verify" && action !== "guilds" && action !== "await-telegram-start") {
+            if (action !== "verify" && action !== "guilds" && action !== "channels" && action !== "await-telegram-start") {
                 return json(res, 400, { error: "unknown probe" });
             }
             const platform = body.platform === "discord" ? "discord" : "telegram";
             // The token is read, used for one outbound call, and dropped. It is never
             // logged and never echoed back in the response.
             ctx.logger.info({ action, platform }, "settings: quickstart probe");
-            const result = await runProviderProbe({ action, platform, token, offset: typeof body.offset === "number" ? body.offset : 0 }, { isTokenInUse: candidate => ctx.isBotTokenInUse?.(candidate) ?? false });
+            const result = await runProviderProbe({ action, platform, token, offset: typeof body.offset === "number" ? body.offset : 0, guild_id: typeof body.guild_id === "string" ? body.guild_id : "" }, { isTokenInUse: candidate => ctx.isBotTokenInUse?.(candidate) ?? false });
             json(res, result.ok ? 200 : 409, result);
         }).catch(() => json(res, 400, { error: "bad request" }));
         return true;
@@ -274,14 +373,30 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             catch {
                 return json(res, 400, { error: "invalid JSON" });
             }
-            const invalid = validateWizardInput(body);
+            const invalid = validateWizardInput(body, { tokenEnvOptional: true });
             if (invalid)
                 return json(res, 400, { error: invalid });
-            json(res, 200, planQuickstart(body, {
-                backends: detectWizardBackends(),
+            const channels = wizardChannels(cfg);
+            const conflict = newConnectionConflict(body, { channels }) ?? agentConflict(body, cfg);
+            if (conflict)
+                return json(res, 409, { error: conflict });
+            // A generated name avoids every name already held: connections', providers', this data dir's .env, this process's.
+            let envFile;
+            try {
+                envFile = envFileKeys(ctx.dataDir);
+            }
+            catch (err) {
+                if (err instanceof EnvFileUnreadableError)
+                    return json(res, 503, { error: err.message });
+                throw err;
+            }
+            const taken = takenTokenEnvNames({ channelEnvs: channels.map(c => c.token_env), envFile, processEnv: Object.keys(process.env) });
+            json(res, 200, withTopicRelease(planQuickstart(withExistingAgent(body, cfg), {
+                backends: body.connection_only ? [] : detectWizardBackends(),
                 has_fleet: Object.keys(cfg.instances ?? {}).length > 0,
-                channels: wizardChannels(cfg),
-            }));
+                channels,
+                taken_env: taken,
+            }), cfg, body));
         }).catch(() => json(res, 400, { error: "bad request" }));
         return true;
     }
@@ -306,7 +421,11 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             if (!body.token)
                 return json(res, 400, { error: "token required" });
             const summary = wizardChannels(cfg);
-            const plan = planQuickstart(body, {
+            // Never a replacement (#1519 P1, S1): an id or token env another connection holds is refused before anything moves.
+            const conflict = newConnectionConflict(body, { channels: summary }) ?? agentConflict(body, cfg);
+            if (conflict)
+                return json(res, 409, { error: conflict });
+            const plan = planQuickstart(withExistingAgent(body, cfg), {
                 backends: detectWizardBackends(),
                 has_fleet: Object.keys(cfg.instances ?? {}).length > 0,
                 channels: summary,
@@ -325,19 +444,35 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             if (!lease)
                 return json(res, 409, { error: "another secret operation is still running" });
             let stored = false, secretBefore;
-            const before = { channels: cfg.channels, channel: cfg.channel, instance: cfg.instances[body.instance_name],
-                hadInstance: Object.hasOwn(cfg.instances, body.instance_name) };
+            const agent = !body.connection_only;
+            const before = { channels: cfg.channels, channel: cfg.channel, instance: agent ? cfg.instances[body.instance_name] : undefined,
+                hadInstance: agent && Object.hasOwn(cfg.instances, body.instance_name) };
             let store;
             const rollback = {};
             try {
                 execution?.assert();
+                // A generated name is re-checked here, under the .env lease, against what the write would overwrite (#1529 review).
+                if (body.token_env_generated) {
+                    let stale;
+                    try {
+                        stale = generatedTokenEnvStale(body.token_env, { dataDir: ctx.dataDir, channelEnvs: summary.map(c => c.token_env) });
+                    }
+                    catch (err) {
+                        if (err instanceof EnvFileUnreadableError)
+                            return json(res, 503, { error: err.message });
+                        throw err;
+                    }
+                    if (stale)
+                        return json(res, 409, { error: stale }); // nothing written yet; the lease goes in finally
+                }
                 store = new SecretStore(envPath, new Set([body.token_env]), { owner: lease.owner });
                 settingsWrite(req, () => {
                     secretBefore = store.write(body.token_env, body.token);
                     stored = true;
                     cfg.channels = draft.channels;
                     delete cfg.channel;
-                    Object.defineProperty(cfg.instances, body.instance_name, { value: draft.instances[body.instance_name], enumerable: true, writable: true, configurable: true });
+                    if (agent)
+                        Object.defineProperty(cfg.instances, body.instance_name, { value: draft.instances[body.instance_name], enumerable: true, writable: true, configurable: true });
                     const undo = ctx.saveFleetConfig();
                     if (typeof undo === "function")
                         rollback.config = undo;
@@ -352,7 +487,7 @@ export function handleQuickstartRequest(req, res, url, ctx) {
                     delete cfg.channel;
                 if (before.hadInstance)
                     cfg.instances[body.instance_name] = before.instance;
-                else
+                else if (agent)
                     delete cfg.instances[body.instance_name];
                 let cleanupFailed = false;
                 try {
@@ -376,7 +511,7 @@ export function handleQuickstartRequest(req, res, url, ctx) {
             finally {
                 lease.release();
             }
-            ctx.logger.info({ instance: body.instance_name, platform: body.platform }, "settings: quickstart committed");
+            ctx.logger.info({ instance: agent ? body.instance_name : null, connection: plan.channel_id, platform: body.platform }, "settings: quickstart committed");
             // No apply here: the page starts the ordinary job so the wizard's last
             // step has the same progress, deadline and restart recovery as everything
             // else the panel applies.