fix: migrate renamed channels in place

apps/server/openapi.json

@@ -1300,6 +1300,33 @@
 																			},
 																			"required": ["type", "name", "provider"]
 																		},
+																		"previousAddress": {
+																			"type": "object",
+																			"properties": {
+																				"type": {
+																					"type": "string",
+																					"enum": [
+																						"environment",
+																						"vault",
+																						"memory_store",
+																						"skill",
+																						"agent",
+																						"template",
+																						"deployment",
+																						"file",
+																						"identity",
+																						"channel"
+																					]
+																				},
+																				"name": {
+																					"type": "string"
+																				},
+																				"provider": {
+																					"type": "string"
+																				}
+																			},
+																			"required": ["type", "name", "provider"]
+																		},
 																		"reason": {
 																			"type": "string"
 																		},

apps/webui/src/lib/api/generated/schema.d.ts

@@ -731,6 +731,22 @@ export interface paths {
 											name: string;
 											provider: string;
 										};
+										previousAddress?: {
+											/** @enum {string} */
+											type:
+												| "environment"
+												| "vault"
+												| "memory_store"
+												| "skill"
+												| "agent"
+												| "template"
+												| "deployment"
+												| "file"
+												| "identity"
+												| "channel";
+											name: string;
+											provider: string;
+										};
 										reason: string;
 										/** @enum {string} */
 										driftKind?: "none" | "local" | "remote" | "both";

packages/sdk/src/internal/executor/executor.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { UserError } from "../errors.ts";
 import { computeComparableDesiredHash } from "../planner/comparable.ts";
 import { getResourceDeclaration } from "../planner/declaration.ts";
-import { computeResourceHash } from "../planner/hasher.ts";
+import { computeReplacementFingerprint, computeResourceHash } from "../planner/hasher.ts";
 import { buildReadinessBaseline } from "../planner/plan-semantics.ts";
 import { ApiError, ConflictError } from "../providers/base-client.ts";
 import { readComparableIfSupported } from "../providers/drift-support.ts";
@@ -229,8 +229,8 @@ async function executeAction(action: PlannedAction, provider: ResourceExecAdapte
 			resource: action.address,
 			message: `update ${action.address.type}.${action.address.name} (${action.address.provider}) — not found remotely, recreating`,
 		});
-		ctx.state.removeResource(action.address);
-		return executeActionInner({ ...action, action: "create" }, provider, ctx);
+		ctx.state.removeResource(action.previousAddress ?? action.address);
+		return executeActionInner({ ...action, action: "create", previousAddress: undefined }, provider, ctx);
 	}
 }
 
@@ -317,7 +317,8 @@ async function executeActionInner(
 	}
 
 	const isUpdate = action.action === "update";
-	const existingId = isUpdate ? ctx.state.getResource(address)?.remote_id : undefined;
+	const priorAddress = action.previousAddress ?? address;
+	const existingId = isUpdate ? ctx.state.getResource(priorAddress)?.remote_id : undefined;
 
 	let result: RemoteResource;
 
@@ -652,7 +653,7 @@ async function executeActionInner(
 
 	// The externally-managed marker is sticky: it survives applies and is only
 	// cleared by removing the resource from state (`agents state rm` / destroy).
-	const priorResource = ctx.state.getResource(address);
+	const priorResource = ctx.state.getResource(priorAddress);
 	ctx.state.setResource({
 		address,
 		remote_id: result.id,
@@ -669,9 +670,11 @@ async function executeActionInner(
 		desired_readiness_baseline: buildReadinessBaseline(getResourceDeclaration(address, ctx.config)),
 		remote_hash: remoteHash,
 		remote_snapshot: remoteSnapshot,
+		replacement_fingerprint: computeReplacementFingerprint(address, ctx.config),
 		drift_paths: [],
 		drift_status: remoteHash ? "in_sync" : undefined,
 	});
+	if (action.previousAddress) ctx.state.removeResource(action.previousAddress);
 	return adopted;
 }
 
@@ -719,6 +722,16 @@ async function adoptOnConflict(
 // command, so fail with actionable guidance instead of the raw wire error.
 function nameReservedError(err: unknown, address: ResourceAddress, searchName: string): UserError {
 	const detail = err instanceof ApiError ? err.message : String(err);
+	if (
+		address.type === "channel" &&
+		err instanceof ApiError &&
+		err.responseBody.includes("CHANNEL_CREDENTIAL_CONFLICT")
+	) {
+		return new UserError(
+			`${address.provider} rejected channel.${address.name} because its credentials are already used by another Channel. ` +
+				`Keep the existing Channel address so it can be updated in place, remove the old Channel first, or use a different credential set. (${detail})`,
+		);
+	}
 	return new UserError(
 		`${address.provider} reported ${address.type} "${searchName}" already exists, but it could not be found remotely to adopt. ` +
 			`This usually means it was recently deleted and the provider still reserves the name. ` +

packages/sdk/src/internal/planner/hasher.ts

@@ -51,6 +51,14 @@ export async function computeResourceHash(
 	return contentHash(decl);
 }
 
+/** Stable, non-reversible identity hint for resources whose YAML key may change. */
+export function computeReplacementFingerprint(address: ResourceAddress, config: ProjectConfig): string | undefined {
+	if (address.type !== "channel") return undefined;
+	const decl = config.channels?.[address.name];
+	if (!decl) return undefined;
+	return contentHash({ channel_type: decl.type, credentials: decl.credentials ?? {} });
+}
+
 function resolveChannelReferenceIds(
 	decl: { agent: string; identity?: string },
 	config: ProjectConfig,

packages/sdk/src/internal/planner/planner.ts

@@ -10,7 +10,7 @@ import type { ExecutionPlan, PlannedAction } from "../types/plan.ts";
 import type { ResourceAddress, StateFile } from "../types/state.ts";
 import { addressKey } from "../types/state.ts";
 import { getResourceDeclaration } from "./declaration.ts";
-import { computeResourceHash } from "./hasher.ts";
+import { computeReplacementFingerprint, computeResourceHash } from "./hasher.ts";
 import { buildReadinessBaseline, classifyReadinessImpact, diffReadinessBaseline } from "./plan-semantics.ts";
 
 export interface PlanOptions {
@@ -218,9 +218,92 @@ export async function buildPlan(
 		});
 	}
 
+	coalesceChannelRenames(actions, config, state);
 	return { actions, diagnostics: diagnostics.getAll() };
 }
 
+/**
+ * A YAML key is a resource address, but changing that key should not force a
+ * remote Channel replacement when the old and new declarations form one
+ * unambiguous same-type pair. Retaining the remote id is especially important
+ * for messaging providers that allow a credential set to belong to only one
+ * Channel at a time.
+ */
+function coalesceChannelRenames(actions: PlannedAction[], config: ProjectConfig, state: StateFile): void {
+	const creates = actions.filter((action) => action.action === "create" && action.address.type === "channel");
+	const deletes = actions.filter((action) => action.action === "delete" && action.address.type === "channel");
+	const stateByAddress = new Map(state.resources.map((resource) => [addressKey(resource.address), resource]));
+	const matchedDeletes = new Set<PlannedAction>();
+
+	for (const create of creates) {
+		const desiredType = config.channels?.[create.address.name]?.type;
+		if (!desiredType) continue;
+		const desiredFingerprint = computeReplacementFingerprint(create.address, config);
+		const candidates = deletes.filter((deletion) => {
+			if (matchedDeletes.has(deletion) || deletion.address.provider !== create.address.provider) return false;
+			const prior = stateByAddress.get(addressKey(deletion.address));
+			const snapshot = prior?.remote_snapshot as { channel_type?: unknown } | undefined;
+			if (snapshot?.channel_type !== desiredType) return false;
+			return !prior?.replacement_fingerprint || prior.replacement_fingerprint === desiredFingerprint;
+		});
+		if (candidates.length !== 1) continue;
+
+		const deletion = candidates[0]!;
+		const prior = stateByAddress.get(addressKey(deletion.address));
+		const competingCreates = creates.filter(
+			(candidate) =>
+				candidate !== create &&
+				candidate.address.provider === create.address.provider &&
+				config.channels?.[candidate.address.name]?.type === desiredType &&
+				(!prior?.replacement_fingerprint ||
+					computeReplacementFingerprint(candidate.address, config) === prior.replacement_fingerprint),
+		);
+		if (competingCreates.length > 0) continue;
+
+		create.action = "update";
+		create.previousAddress = deletion.address;
+		create.before = deletion.before;
+		create.driftKind = "local";
+		create.reason = `Channel key renamed from '${deletion.address.name}' (remote resource retained)`;
+		protectRenamedChannelDependencies(actions, stateByAddress, deletion, create);
+		matchedDeletes.add(deletion);
+	}
+
+	for (let index = actions.length - 1; index >= 0; index--) {
+		if (matchedDeletes.has(actions[index]!)) actions.splice(index, 1);
+	}
+}
+
+/** Do not delete the old Identity/Template when the Channel migration that releases it fails. */
+function protectRenamedChannelDependencies(
+	actions: PlannedAction[],
+	stateByAddress: Map<string, StateFile["resources"][number]>,
+	deletion: PlannedAction,
+	replacement: PlannedAction,
+): void {
+	const prior = stateByAddress.get(addressKey(deletion.address));
+	const snapshot = prior?.remote_snapshot as { identity_id?: unknown; template_id?: unknown } | undefined;
+	const referencedIds = new Set(
+		[snapshot?.identity_id, snapshot?.template_id].filter((id): id is string => typeof id === "string"),
+	);
+	if (referencedIds.size === 0) return;
+
+	for (const action of actions) {
+		if (
+			action.action !== "delete" ||
+			(action.address.type !== "identity" && action.address.type !== "template") ||
+			action.address.provider !== replacement.address.provider
+		) {
+			continue;
+		}
+		const dependency = stateByAddress.get(addressKey(action.address));
+		if (!dependency?.remote_id || !referencedIds.has(dependency.remote_id)) continue;
+		if (!action.dependencies.some((address) => addressKey(address) === addressKey(replacement.address))) {
+			action.dependencies.push(replacement.address);
+		}
+	}
+}
+
 /** Keep the old delivery resource alive when creating its new materialization fails. */
 function deliveryReplacementAddress(address: ResourceAddress, graph: DependencyGraph): ResourceAddress | undefined {
 	if (address.type !== "agent" && address.type !== "template") return undefined;

packages/sdk/src/internal/state/state-manager.ts

@@ -47,6 +47,7 @@ export class StateManager implements IStateManager {
 				desired_readiness_baseline: r.desired_readiness_baseline as ResourceState["desired_readiness_baseline"],
 				remote_hash: r.remote_hash as string | undefined,
 				remote_snapshot: r.remote_snapshot,
+				replacement_fingerprint: r.replacement_fingerprint as string | undefined,
 				drift_paths: r.drift_paths as string[] | undefined,
 				drift_status: r.drift_status as ResourceState["drift_status"],
 			}));

packages/sdk/src/internal/types/dto.ts

@@ -44,6 +44,8 @@ export type PlanReadinessImpact = z.infer<typeof PlanReadinessImpactSchema>;
 export const PlannedActionSchema = z.object({
 	action: ActionTypeSchema,
 	address: ResourceAddressSchema,
+	/** Existing state address to retain when this action is an inferred logical rename. */
+	previousAddress: ResourceAddressSchema.optional(),
 	reason: z.string(),
 	driftKind: DriftKindSchema.optional(),
 	readinessImpact: PlanReadinessImpactSchema.optional(),

packages/sdk/src/internal/types/state.ts

@@ -21,6 +21,8 @@ export interface ResourceState {
 	desired_readiness_baseline?: ResourceReadinessBaseline;
 	remote_hash?: string;
 	remote_snapshot?: unknown;
+	/** Non-reversible declaration fingerprint used to infer safe logical renames. */
+	replacement_fingerprint?: string;
 	drift_paths?: string[];
 	drift_status?: "in_sync" | "drifted" | "missing" | "unchecked";
 }