@songsid/agend 2.2.0-alpha.9 → 2.2.0-beta.10

package/dist/outbound-handlers.js

@@ -1,17 +1,17 @@
-import { validateFleetConfig } from "./config-validator.js";
+import { KNOWN_BACKENDS, validateFleetConfig } from "./config-validator.js";
 import { resolve as pathResolve, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { deliveryContentDigest, deliveryStatusSelector } from "./delivery-outbox.js";
 import { GENERAL_PAUSE_ERROR, isGeneralInstance } from "./general-instance.js";
-import { DEFAULT_MAX_CROSS_INSTANCE_MESSAGE_BYTES, DEFAULT_LIST_INSTANCES_OUTPUT_BUDGET, MAX_INSTANCE_LOG_LINES } from "./config.js";
+import { DEFAULT_MAX_CROSS_INSTANCE_MESSAGE_BYTES, DEFAULT_LIST_INSTANCES_OUTPUT_BUDGET, MAX_INSTANCE_LOG_LINES, getEffectiveInstanceDefaults } from "./config.js";
 import { t } from "./locale.js";
 import { presentationState, interactionSummary } from "./interaction-observation.js";
 import { truncatePreview } from "./channel/markdown-chunk.js";
 import { crossInstanceVisibility, senderTopicNotice, targetTopicNotice } from "./cross-instance-notice.js";
 import { instanceSupportsSteer } from "./steer-capability.js";
 import { assignDisplayLabels, displayInstanceName, readStatuslineModel } from "./topic-commands.js";
-import { credentialProfileLogin, credentialSwitchStartsFresh, instanceCredentialProfile } from "./backend/credential-profile.js";
+import { CHAT_PROFILE_LOGIN_BACKENDS, credentialProfileLogin, credentialSwitchCarriesConversation, credentialSwitchStartsFresh, instanceCredentialProfile } from "./backend/credential-profile.js";
 import { kiroEngineCandidates, kiroEngineStatus } from "./kiro-engine-status.js";
 import { formatCrossInstanceInboundMessage, MAX_ASSEMBLED_CROSS_INSTANCE_MESSAGE_BYTES, } from "./cross-instance-envelope.js";
 import { BroadcastArgs, CreateInstanceArgs, CreateTeamArgs, DelegateTaskArgs, DeleteInstanceArgs, DeleteTeamArgs, DeployTemplateArgs, DescribeInstanceArgs, ListDeploymentsArgs, ListInstancesArgs, ListTeamsArgs, ReplaceInstanceArgs, ReportResultArgs, DeliveryStatusArgs, RequestInformationArgs, RestartInstanceArgs, SendToInstanceArgs, PauseInstanceArgs, WakeInstanceArgs, StopInstanceArgs, GetInstanceLogsArgs, GetEffortArgs, KiroEngineStatusArgs, GetUsageArgs, ListModelsArgs, GetFleetConfigArgs, UpdateInstanceConfigArgs, UpdateFleetDefaultsArgs, StartInstanceArgs, TeardownDeploymentArgs, UpdateTeamArgs, validateArgs, } from "./outbound-schemas.js";
@@ -32,8 +32,11 @@ function rejectOversizedCrossInstanceMessage(ctx, message, respond) {
     respond(null, t("cross_instance.message_too_large", formatByteSize(actual), formatByteSize(limit)));
     return true;
 }
-function rejectOversizedCrossInstanceEnvelope(message, meta, respond) {
-    const actual = Buffer.byteLength(formatCrossInstanceInboundMessage(message, meta), "utf8");
+function rejectOversizedCrossInstanceEnvelope(message, meta, respond, 
+/** #1650: the footer differs by the receiver's mode — its own, or the longer of the two when targets are not known yet. */
+mode = "mcp") {
+    const size = (m) => Buffer.byteLength(formatCrossInstanceInboundMessage(message, meta, m), "utf8");
+    const actual = mode === "either" ? Math.max(size("mcp"), size("cli")) : size(mode);
     if (actual <= MAX_ASSEMBLED_CROSS_INSTANCE_MESSAGE_BYTES)
         return false;
     respond(null, t("cross_instance.envelope_too_large", formatByteSize(actual), formatByteSize(MAX_ASSEMBLED_CROSS_INSTANCE_MESSAGE_BYTES)));
@@ -165,7 +168,7 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         respond(null, v.error);
         return;
     }
-    const { instance_name: targetName, message, steer, request_kind: reqKind, requires_reply, task_summary, working_directory, branch, correlation_id: parsedCorrelationId } = v.data;
+    const { instance_name: targetName, message, forwards, steer, request_kind: reqKind, requires_reply, task_summary, working_directory, branch, correlation_id: parsedCorrelationId } = v.data;
     if (rejectOversizedCrossInstanceMessage(ctx, message, respond))
         return;
     const senderLabel = meta.senderSessionName ?? meta.instanceName;
@@ -221,7 +224,7 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
     const queuedPredecessor = steerCapable
         && ctx.hasPendingIdleGatedDelivery?.(targetInstanceName) === true;
     const useSteer = steerCapable && !queuedPredecessor;
-    const steerFallbackWarning = steer === true && !useSteer
+    let steerFallbackWarning = steer === true && !useSteer
         ? isExternalSession
             ? t("delivery.steer_external")
             : queuedPredecessor
@@ -252,12 +255,14 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         ipcMeta.working_directory = working_directory;
     if (branch)
         ipcMeta.branch = branch;
+    if (forwards?.length)
+        ipcMeta.forwards = JSON.stringify(forwards);
     // #77: surface the sender's display name in the recipient's [from:…] header
     // (keeps from_instance as the machine name so the reply-back target stays valid).
     const senderDisplay = ctx.fleetConfig?.instances[senderLabel]?.display_name;
     if (senderDisplay && senderDisplay !== senderLabel)
         ipcMeta.from_display = senderDisplay;
-    if (rejectOversizedCrossInstanceEnvelope(message, ipcMeta, respond))
+    if (rejectOversizedCrossInstanceEnvelope(message, ipcMeta, respond, ctx.fleetConfig?.instances[targetName]?.agent_mode === "cli" ? "cli" : "mcp"))
         return;
     // Fire-and-queue: hand the message to the fleet and respond immediately.
     // deliverToInstance owns waking a paused target, the idle gate and retries;
@@ -275,6 +280,7 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         meta: ipcMeta,
     };
     let durableReceipt;
+    let effectiveUseSteer = useSteer;
     if (ctx.admitDurableDelivery) {
         try {
             durableReceipt = ctx.admitDurableDelivery({
@@ -288,7 +294,13 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
                 kind: useSteer ? "steer" : "fleet_inbound",
                 correlationId,
                 payload,
+                forwards,
+                requestedKind: steer === true ? "steer" : "fleet_inbound",
             });
+            if (durableReceipt.kind)
+                effectiveUseSteer = durableReceipt.kind === "steer";
+            if (durableReceipt.duplicate && durableReceipt.kind !== undefined && durableReceipt.kind !== payload.type)
+                steerFallbackWarning = undefined;
         }
         catch (err) {
             ctx.logger.error({ err, source: meta.instanceName, target: targetInstanceName }, "Durable outbound admission failed closed");
@@ -297,6 +309,10 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         }
     }
     else {
+        if (forwards?.length) {
+            respond(null, "Forwarded message verification requires the durable delivery store");
+            return;
+        }
         // Standalone handler harnesses retain the legacy path; production FleetManager
         // always provides durable admission.
         void deliverCrossInstanceWithRetry(ctx, targetInstanceName, targetName, senderLabel, correlationId, payload, useSteer ? { isCrossInstance: true, waitForIdle: false } : undefined);
@@ -333,33 +349,43 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         displayName: ctx.fleetConfig?.instances[name]?.display_name,
     })));
     const displayLabel = (name) => fleetLabels.get(name) ?? displayInstanceName(name, ctx.fleetConfig?.instances[name]?.display_name);
+    const instances = ctx.fleetConfig?.instances ?? {};
+    const notice = { label: `${displayLabel(senderLabel)} → ${displayLabel(targetName)}`, message, requestKind, taskSummary: ipcMeta.task_summary };
+    const targetInstance = instances[targetInstanceName];
+    const targetIsGeneral = targetInstance?.general_topic === true;
+    const targetText = targetTopicNotice(crossInstanceVisibility(ctx.fleetConfig, targetInstanceName), notice);
+    const targetShown = targetText !== null && !targetIsGeneral && !ctx.sessionRegistry.has(targetName);
+    const senderInstance = instances[meta.instanceName];
+    const senderIsGeneral = senderInstance?.general_topic === true;
+    const senderText = senderTopicNotice(crossInstanceVisibility(ctx.fleetConfig, meta.instanceName), notice);
+    const senderShown = senderText !== null && !senderIsGeneral;
     if (groupId && ctx.adapter) {
-        const instances = ctx.fleetConfig?.instances ?? {};
-        const notificationLabel = `${displayLabel(senderLabel)} → ${displayLabel(targetName)}`;
-        const notice = { label: notificationLabel, message, requestKind, taskSummary: ipcMeta.task_summary };
         // ── Target topic notification ──
-        const targetInstance = instances[targetInstanceName];
         const targetTopicId = targetInstance?.topic_id;
-        const targetIsGeneral = targetInstance?.general_topic === true;
-        const targetText = targetTopicNotice(crossInstanceVisibility(ctx.fleetConfig, targetInstanceName), notice);
-        if (targetText !== null && targetTopicId && !targetIsGeneral && !ctx.sessionRegistry.has(targetName)) {
+        if (targetShown && targetTopicId) {
             const targetAdapter = ctx.getAdapterForInstance?.(targetInstanceName) ?? ctx.adapter;
             const targetGroupId = ctx.getGroupIdForInstance?.(targetInstanceName) ?? String(groupId);
             targetAdapter.sendText(String(targetGroupId), targetText, { threadId: String(targetTopicId) })
                 .catch(e => ctx.logger.warn({ err: e }, "Failed to post target topic notification"));
         }
         // ── Sender topic notification ──
-        const senderInstance = instances[meta.instanceName];
         const senderTopicId = senderInstance?.topic_id;
-        const senderIsGeneral = senderInstance?.general_topic === true;
-        const senderText = senderTopicNotice(crossInstanceVisibility(ctx.fleetConfig, meta.instanceName), notice);
-        if (senderText !== null && senderTopicId && !senderIsGeneral) {
+        if (senderShown && senderTopicId) {
             const senderAdapter = ctx.getAdapterForInstance?.(meta.instanceName) ?? ctx.adapter;
             const senderGroupId = ctx.getGroupIdForInstance?.(meta.instanceName) ?? String(groupId);
             senderAdapter.sendText(senderGroupId, senderText, { threadId: String(senderTopicId) })
                 .catch(e => ctx.logger.warn({ err: e }, "Failed to post sender topic notification"));
         }
     }
+    // #1672: the same notices in each instance's web chat — a muted status line, never an agent's or a person's message.
+    // Not gated on a topic or a chat platform (a web-only fleet, a topic-less instance); recorded in its history (#1565).
+    const webNotice = (instance, text) => ctx.emitSseEvent?.("message", {
+        instance, sender: displayLabel(senderLabel), role: "status", text, ts: new Date().toISOString(),
+    });
+    if (targetShown)
+        webNotice(targetInstanceName, targetText);
+    if (senderShown)
+        webNotice(meta.instanceName, senderText);
     // #856: the same line, now carrying the envelope's message_id and a short
     // content digest, so a disputed message can be matched to its outbox row
     // and paste digests without adding a log line per delivery.
@@ -379,6 +405,7 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
         : undefined;
     const warnings = [steerFallbackWarning, targetStateWarning].filter((value) => !!value);
     respond({ sent: true, queued: true, target: targetName, target_state: state,
+        ...(forwards?.length ? { forwards } : {}),
         ...(durableReceipt ? {
             durable: true,
             delivery_id: durableReceipt.deliveryId,
@@ -387,8 +414,8 @@ const sendToInstance = async (ctx, rawArgs, respond, meta) => {
             duplicate: durableReceipt.duplicate,
         } : {}),
         ...(state === "paused" ? { waking: true } : {}), correlation_id: correlationId,
-        ...(useSteer ? { delivery_mode: "steer" } : {}),
-        ...(steerFallbackWarning ? { delivery_mode: "idle_queue" } : {}),
+        ...(effectiveUseSteer ? { delivery_mode: "steer" } : {}),
+        ...(steer === true && !effectiveUseSteer ? { delivery_mode: "idle_queue" } : {}),
         ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}),
     });
 };
@@ -918,31 +945,86 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
         respond(null, v.error);
         return;
     }
-    const inst = ctx.fleetConfig?.instances[v.data.name];
+    applyInstanceConfigPatch(ctx, v.data.name, v.data.config, respond);
+};
+/**
+ * update_instance_config's write: one validated config write, rolled back whole on a refusal, then one relaunch when
+ * the backend (fresh, #1217), a credential profile or backend_options changed. Answers through `respond` like the tool.
+ */
+export function applyInstanceConfigPatch(ctx, name, patch, respond) {
+    const inst = ctx.fleetConfig?.instances[name];
     if (!inst) {
         const isClassic = (ctx.classicChannels?.getAll() ?? [])
-            .some(channel => channel.instanceName === v.data.name);
+            .some(channel => channel.instanceName === name);
         respond(null, isClassic
             ? "This is a ClassicBot instance (managed in classicBot.yaml). Use set_display_name or set_description to configure it."
-            : `Instance '${v.data.name}' not found in fleet config`);
+            : `Instance '${name}' not found in fleet config`);
         return;
     }
-    const patch = v.data.config;
     // Read before anything is mutated: the switch is what decides whether the
     // next launch may resume, and by then `inst` already holds the new value.
-    const backendBefore = inst.backend ?? "claude-code";
+    // The backend an instance runs: its own, else the fleet default (#1815 review: a Settings-created entry may omit it).
+    const effectiveBackend = () => inst.backend ?? ctx.fleetConfig?.defaults?.backend ?? "claude-code";
+    const backendBefore = effectiveBackend();
+    // #1808: a model and an effort name the backend they were chosen for. On a switch the new backend gets the ones
+    // given — if it takes them, refused here before anything is written — or none of the instance's own (the inherited
+    // value, else the CLI's default). Never the old backend's: codex launched with `--model opus` fails every turn.
+    if (patch.backend !== undefined && patch.backend !== backendBefore) {
+        const backendNew = patch.backend;
+        // Only a backend AgEnD knows gets these checks; any other name is refused by validation below, as before (and a
+        // "__proto__" or "toString" never reaches a lookup keyed by backend name).
+        const known = KNOWN_BACKENDS.includes(backendNew);
+        // The provider the new backend will run on (#1815 review): this patch's backend_options over the instance's, else
+        // the fleet defaults' — a custom provider has its own catalog, which the account's list says nothing about.
+        const options = mergeBackendOptions(inst.backend_options, patch.backend_options ?? {})[backendNew]
+            ?? ctx.fleetConfig?.defaults?.backend_options?.[backendNew];
+        const rawProvider = options?.provider;
+        const provider = typeof rawProvider === "string" && rawProvider.trim() ? rawProvider.trim() : null;
+        if (known && typeof patch.model === "string") {
+            const verdict = ctx.backendModelVerdict?.(name, backendNew, patch.model, { provider });
+            if (verdict && !verdict.ok) {
+                respond(null, `Rejected: ${backendNew} does not take the model "${patch.model}". ${verdict.choices.length
+                    ? `Choose one of: ${verdict.choices.join(", ")}` : `No ${backendNew} model list is known yet`} — or leave model out for its default.`);
+                return;
+            }
+        }
+        if (known && typeof patch.effort === "string") {
+            // The levels of the model that will run there (codex's differ per model): the one given, else the inherited one.
+            const inheritedModel = getEffectiveInstanceDefaults(ctx.fleetConfig?.defaults).model;
+            const runs = typeof patch.model === "string" ? patch.model : typeof inheritedModel === "string" ? inheritedModel : null;
+            const levels = ctx.backendEffortLevels?.(name, backendNew, runs);
+            if (levels && !levels.includes(patch.effort)) {
+                respond(null, levels.length
+                    ? `Rejected: ${backendNew} takes no effort "${patch.effort}" at launch on this host. Choose one of: ${levels.join(", ")} — or leave effort out for its default.`
+                    : `Rejected: ${backendNew} takes no effort at launch on this host — leave effort out.`);
+                return;
+            }
+        }
+        patch = { ...patch, model: patch.model === undefined ? null : patch.model, effort: patch.effort === undefined ? null : patch.effort };
+    }
     const profileBefore = instanceCredentialProfile(inst, ctx.fleetConfig?.defaults, backendBefore);
     // Snapshot enough to undo the whole patch if validation refuses it.
     const beforeEdit = validateFleetConfig(ctx.fleetConfig);
     const beforeFields = {};
-    for (const key of ["backend", "model", "auto_pause_after", "display_name", "description"]) {
+    for (const key of ["backend", "model", "effort", "auto_pause_after", "display_name", "description"]) {
         if (patch[key] !== undefined)
             beforeFields[key] = inst[key];
     }
     if (patch.backend !== undefined)
         inst.backend = patch.backend;
-    if (patch.model !== undefined)
-        inst.model = patch.model;
+    // null: the value this instance would have with no override of its own — what loading fleet.yaml gives it.
+    const inherited = getEffectiveInstanceDefaults(ctx.fleetConfig?.defaults);
+    for (const key of ["model", "effort"]) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        if (value !== null)
+            inst[key] = value;
+        else if (inherited[key] !== undefined)
+            inst[key] = inherited[key];
+        else
+            delete inst[key];
+    }
     if (patch.auto_pause_after !== undefined)
         inst.auto_pause_after = patch.auto_pause_after;
     if (patch.display_name !== undefined)
@@ -956,20 +1038,7 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
     let relaunchNeeded = false;
     if (patch.backend_options !== undefined) {
         const before = JSON.stringify(previousOptions ?? {});
-        const merged = { ...(previousOptions ?? {}) };
-        for (const [backendName, options] of Object.entries(patch.backend_options)) {
-            const namespace = { ...(merged[backendName] ?? {}), ...options };
-            // A merge cannot express removal, so null (or "") means "drop this key"
-            // — that is how an agent goes back to the fleet's default login.
-            for (const [key, value] of Object.entries(options)) {
-                if (value === null || value === "")
-                    delete namespace[key];
-            }
-            if (Object.keys(namespace).length)
-                merged[backendName] = namespace;
-            else
-                delete merged[backendName];
-        }
+        const merged = mergeBackendOptions(previousOptions, patch.backend_options);
         inst.backend_options = merged;
         relaunchNeeded = JSON.stringify(merged) !== before;
     }
@@ -997,7 +1066,7 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
         respond(null, `Rejected: ${introduced.map(issue => `${issue.path}: ${issue.message}`).join("; ")}`);
         return;
     }
-    const backendAfter = inst.backend ?? "claude-code";
+    const backendAfter = effectiveBackend();
     const profileAfter = instanceCredentialProfile(inst, ctx.fleetConfig?.defaults, backendAfter);
     const profileSwitched = profileAfter !== profileBefore;
     // #1217: a running CLI is the backend it was launched as. Saving a new
@@ -1020,13 +1089,17 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
     // the escape hatch from a bad switch and must never be the thing that is
     // blocked, and an unlogged shared store means the CLI was never set up at
     // all — a state that predates this feature.
-    if (profileSwitched && profileAfter) {
+    // #1806 review: a profile is a login of ONE backend — the same name under another backend is another store, so a
+    // backend switch onto a named profile is checked too (claude-code "personal" says nothing about kiro-cli "personal").
+    if ((profileSwitched || backendSwitched) && profileAfter) {
         // The same root the launcher resolves the profile under, so the store this
         // probes is the store the CLI will be pointed at.
         const login = credentialProfileLogin(ctx.dataDir, backendAfter, profileAfter);
         if (login.state === "signed-out") {
             rollback();
-            respond(null, `Rejected: credential profile "${profileAfter}" has no ${backendAfter} login yet, and switching to it would leave the agent waiting at a sign-in prompt. Log it in first:\n  ${login.loginCommand}`);
+            // #1699 part 2: a claude-code profile can also be signed in from chat, in the browser terminal.
+            const fromChat = CHAT_PROFILE_LOGIN_BACKENDS.has(backendAfter) ? `\n  or from chat: /login ${backendAfter} ${profileAfter}` : "";
+            respond(null, `Rejected: credential profile "${profileAfter}" has no ${backendAfter} login yet, and switching to it would leave the agent waiting at a sign-in prompt. Log it in first:\n  ${login.loginCommand}${fromChat}`);
             return;
         }
     }
@@ -1039,18 +1112,18 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
         return;
     }
     if (!relaunchNeeded) {
-        respond({ success: true, name: v.data.name, applied: patch });
+        respond({ success: true, name, applied: patch });
         return;
     }
     // Only a running instance is restarted. Switching the subscription of a
     // paused or stopped agent must not start it — restartSingleInstance is
     // stop-then-start and would — so the new credentials are read whenever it
     // next comes up on its own.
-    const status = targetState(ctx, v.data.name);
+    const status = targetState(ctx, name);
     if (status !== "running") {
         respond({
             success: true,
-            name: v.data.name,
+            name,
             applied: patch,
             restarted: false,
             note: `Instance is ${status}; the new ${backendSwitched ? "backend" : "backend_options"} apply when it next starts.`,
@@ -1070,19 +1143,26 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
     // was — taking a handover there would be describing a loss that did not
     // happen, and starting fresh would be causing one.
     const switchLosesConversation = profileSwitched && credentialSwitchStartsFresh(backendAfter);
+    // #1753: Claude Code's conversation can go along — copied into the new profile and resumed there, between the old
+    // CLI's stop and the new one's start (the restart does it, and says how it went). The handover is still taken now,
+    // while the daemon that holds it is alive: it is what the new session gets if the copy cannot be made.
+    const carry = profileSwitched && !backendSwitched && credentialSwitchCarriesConversation(backendAfter)
+        ? { backend: backendAfter, from: profileBefore, to: profileAfter, result: null }
+        : null;
     const handover = switchLosesConversation
-        ? (ctx.lifecycle.daemons.get(v.data.name)?.collectHandoverContext() ?? "")
+        ? (ctx.lifecycle.daemons.get(name)?.collectHandoverContext() ?? "")
         : "";
     // Saving without restarting would report a subscription switch that has not
     // happened — the running CLI keeps the credentials it was launched with.
-    // A switch also starts fresh: the new store has no conversation for this
-    // directory, so resuming can only spend the resume startup budget waiting for
-    // something that is not there.
-    ctx.restartSingleInstance(v.data.name, switchLosesConversation || backendSwitched ? { freshStart: true } : undefined).then(async () => {
-        const handoverChars = await deliverProfileHandover(ctx, v.data.name, profileBefore, profileAfter, handover);
+    // A switch that cannot take the conversation along starts fresh: the new store
+    // has no conversation for this directory, so resuming can only spend the
+    // resume startup budget waiting for something that is not there.
+    ctx.restartSingleInstance(name, carry ? { carry } : switchLosesConversation || backendSwitched ? { freshStart: true } : undefined).then(async () => {
+        const carried = carry?.result?.carried === true;
+        const handoverChars = carried ? 0 : await deliverProfileHandover(ctx, name, profileBefore, profileAfter, handover);
         respond({
             success: true,
-            name: v.data.name,
+            name,
             applied: patch,
             restarted: true,
             ...(backendSwitched ? { backend_switched: true, conversation_carried_over: false } : {}),
@@ -1093,21 +1173,43 @@ const updateInstanceConfig = (ctx, rawArgs, respond) => {
                     // across accounts is the thing nobody has been able to test yet,
                     // so this says where the history lives rather than what will
                     // happen when the agent reaches for it.
-                    conversation_carried_over: !switchLosesConversation,
-                    ...(switchLosesConversation
-                        ? { handover_chars: handoverChars }
-                        : { conversation_note: `${backendAfter} keeps its history outside the login, so it is shared across profiles; switching back to a profile returns to the same history.` }),
+                    conversation_carried_over: carried || !switchLosesConversation,
+                    ...(carried
+                        ? { conversation_note: "The conversation was copied into the new profile and resumed there (the old profile keeps its own copy). The next reply re-reads it from a cold cache: one slower, full-price turn." }
+                        : switchLosesConversation
+                            ? { handover_chars: handoverChars, ...(carry?.result && !carry.result.carried ? { carry_failed: carry.result.reason } : {}) }
+                            : { conversation_note: `${backendAfter} keeps its history outside the login, so it is shared across profiles; switching back to a profile returns to the same history.` }),
                 }
                 : {}),
         });
     }, (err) => respond({
         success: true,
-        name: v.data.name,
+        name,
         applied: patch,
         restarted: false,
         warning: `Config saved, but the restart failed: ${err.message}. The new backend_options take effect on the next start.`,
     }));
-};
+}
+/**
+ * backend_options merged per backend namespace, so setting a kiro option cannot silently drop a codex one. A merge
+ * cannot express removal, so null (or "") means "drop this key" — that is how an agent goes back to the fleet's
+ * default login.
+ */
+function mergeBackendOptions(previous, patch) {
+    const merged = { ...(previous ?? {}) };
+    for (const [backendName, options] of Object.entries(patch)) {
+        const namespace = { ...(merged[backendName] ?? {}), ...options };
+        for (const [key, value] of Object.entries(options)) {
+            if (value === null || value === "")
+                delete namespace[key];
+        }
+        if (Object.keys(namespace).length)
+            merged[backendName] = namespace;
+        else
+            delete merged[backendName];
+    }
+    return merged;
+}
 /** Long enough for the relaunched CLI to be listening; matches replace_instance. */
 export const PROFILE_HANDOVER_SETTLE_MS = 3_000;
 /**
@@ -1202,6 +1304,8 @@ function wrapAsSend(schema, toolName, buildArgs, warnMissing) {
             request_kind: kind,
             requires_reply: reply,
             task_summary: summary,
+            ...(v.data.forwards !== undefined
+                ? { forwards: v.data.forwards } : {}),
         };
         // Re-dispatch through the handler map
         return sendToInstance(ctx, newArgs, respond, meta);
@@ -1313,7 +1417,7 @@ const broadcast = async (ctx, rawArgs, respond, meta) => {
     // Validate once before dispatching any target. The placeholders are the
     // longest values generated below, so every real per-target envelope fits if
     // this one does. Keeping this outside the loop prevents partial broadcasts.
-    if (rejectOversizedCrossInstanceEnvelope(message, makeBroadcastMeta("bcast-9999999999999-zzzzzz", "bcast-9999999999999"), respond))
+    if (rejectOversizedCrossInstanceEnvelope(message, makeBroadcastMeta("bcast-9999999999999-zzzzzz", "bcast-9999999999999"), respond, "either"))
         return;
     // Resolve target list: team, explicit targets, tag filter, or all running
     let targetNames;
@@ -1401,30 +1505,50 @@ const broadcast = async (ctx, rawArgs, respond, meta) => {
     });
 };
 // ── Teams ────────────────────────────────────────────────────────────────
+/**
+ * #1692: the one creation of a team — create_team (agents) and POST /ui/teams (the web) both come here. Members must be
+ * instances fleet.yaml defines (own keys; repeats dropped); an existing team is never overwritten (409); a name every
+ * object already has (`__proto__`, `constructor`, `toString`…) is not a team name. The team and its save are one: a
+ * save that throws removes it again (500).
+ */
+export function commitTeamCreate(fleetConfig, args, save) {
+    if (!fleetConfig)
+        return { ok: false, status: 500, error: "Fleet config not available" };
+    if (args.name in Object.prototype)
+        return { ok: false, status: 400, error: `Invalid team name: ${args.name}` };
+    const invalid = args.members.filter(m => !Object.hasOwn(fleetConfig.instances, m));
+    if (invalid.length)
+        return { ok: false, status: 400, error: `Invalid instance names: ${invalid.join(", ")}` };
+    if (fleetConfig.teams && Object.hasOwn(fleetConfig.teams, args.name))
+        return { ok: false, status: 409, error: `Team already exists: ${args.name}` };
+    const createdMap = !fleetConfig.teams;
+    const teams = (fleetConfig.teams ??= {});
+    const members = [...new Set(args.members)];
+    const description = args.description?.trim();
+    teams[args.name] = { members, ...(description ? { description } : {}) };
+    try {
+        save();
+    }
+    catch (err) {
+        delete teams[args.name];
+        if (createdMap)
+            delete fleetConfig.teams;
+        return { ok: false, status: 500, error: `Saving fleet.yaml failed; no team was created: ${err?.message ?? String(err)}` };
+    }
+    return { ok: true, result: { created: args.name, members } };
+}
 const createTeam = (ctx, rawArgs, respond) => {
     const v = validateArgs(CreateTeamArgs, rawArgs, "create_team");
     if (!v.ok) {
         respond(null, v.error);
         return;
     }
-    const { name, members, description } = v.data;
-    if (!ctx.fleetConfig) {
-        respond(null, "Fleet config not available");
-        return;
-    }
-    const invalid = members.filter(m => !ctx.fleetConfig.instances[m]);
-    if (invalid.length) {
-        respond(null, `Invalid instance names: ${invalid.join(", ")}`);
+    const r = commitTeamCreate(ctx.fleetConfig, v.data, () => ctx.saveFleetConfig());
+    if (!r.ok) {
+        respond(null, r.error);
         return;
     }
-    ctx.fleetConfig.teams ??= {};
-    if (ctx.fleetConfig.teams[name]) {
-        respond(null, `Team already exists: ${name}`);
-        return;
-    }
-    ctx.fleetConfig.teams[name] = { members, ...(description ? { description } : {}) };
-    ctx.saveFleetConfig();
-    respond({ created: name, members });
+    respond(r.result);
 };
 const deleteTeam = (ctx, rawArgs, respond) => {
     const v = validateArgs(DeleteTeamArgs, rawArgs, "delete_team");
@@ -1458,31 +1582,74 @@ const listTeams = (ctx, rawArgs, respond) => {
     }));
     respond(result);
 };
+/**
+ * #1689: the one update of a team — update_team (agents) and PATCH /ui/teams/<name> (the web) both come here. Own keys
+ * only: a team or an instance is one fleet.yaml defines (`__proto__` and `constructor` are not); nothing changes unless
+ * everything is valid. `description`: "" clears it. Renaming is not an update (the org chart and agents name teams).
+ * The caller saves fleet.yaml after an ok.
+ */
+export function applyTeamUpdate(fleetConfig, args) {
+    if (!fleetConfig)
+        return { ok: false, status: 500, error: "Fleet config not available" };
+    const teams = fleetConfig.teams;
+    if (!teams || !Object.hasOwn(teams, args.name))
+        return { ok: false, status: 404, error: `Team not found: ${args.name}` };
+    const team = teams[args.name];
+    const invalid = (args.add ?? []).filter(m => !Object.hasOwn(fleetConfig.instances, m));
+    if (invalid.length)
+        return { ok: false, status: 400, error: `Invalid instance names: ${invalid.join(", ")}` };
+    let members = [...team.members];
+    if (args.add?.length)
+        members = [...new Set([...members, ...args.add])];
+    if (args.remove?.length)
+        members = members.filter(m => !args.remove.includes(m));
+    team.members = members;
+    if (args.description !== undefined) {
+        if (args.description.trim())
+            team.description = args.description.trim();
+        else
+            delete team.description;
+    }
+    return { ok: true, result: { name: args.name, members: team.members, description: team.description ?? null } };
+}
+/**
+ * #1689 review: the update and its save as one — a save that fails (an I/O error) puts the team back as it was, so the
+ * live fleet never differs from fleet.yaml; that is a 500 (the input was fine), not a 400.
+ */
+export function commitTeamUpdate(fleetConfig, args, save) {
+    const teams = fleetConfig?.teams;
+    const team = teams && Object.hasOwn(teams, args.name) ? teams[args.name] : null;
+    const before = team ? { members: [...team.members], hadDescription: Object.hasOwn(team, "description"), description: team.description } : null;
+    const r = applyTeamUpdate(fleetConfig, args);
+    if (!r.ok)
+        return r;
+    try {
+        save();
+    }
+    catch (err) {
+        if (team && before) {
+            team.members = before.members;
+            if (before.hadDescription)
+                team.description = before.description;
+            else
+                delete team.description;
+        }
+        return { ok: false, status: 500, error: `Saving fleet.yaml failed; the team is unchanged: ${err?.message ?? String(err)}` };
+    }
+    return r;
+}
 const updateTeam = (ctx, rawArgs, respond) => {
     const v = validateArgs(UpdateTeamArgs, rawArgs, "update_team");
     if (!v.ok) {
         respond(null, v.error);
         return;
     }
-    const { name, add, remove } = v.data;
-    if (!ctx.fleetConfig?.teams?.[name]) {
-        respond(null, `Team not found: ${name}`);
+    const r = commitTeamUpdate(ctx.fleetConfig, v.data, () => ctx.saveFleetConfig());
+    if (!r.ok) {
+        respond(null, r.error);
         return;
     }
-    const team = ctx.fleetConfig.teams[name];
-    if (add?.length) {
-        const invalid = add.filter(m => !ctx.fleetConfig.instances[m]);
-        if (invalid.length) {
-            respond(null, `Invalid instance names: ${invalid.join(", ")}`);
-            return;
-        }
-        team.members = [...new Set([...team.members, ...add])];
-    }
-    if (remove?.length) {
-        team.members = team.members.filter(m => !remove.includes(m));
-    }
-    ctx.saveFleetConfig();
-    respond({ name, members: team.members });
+    respond(r.result);
 };
 // ── Fleet Templates ────────────────────────────────────────────────────
 const deployTemplate = async (ctx, rawArgs, respond) => {