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";
 }

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";
 }

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";
 }

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";
 }

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";
 }

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";
 }

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";
 }

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";
 }