@ganglion/xacpx 0.20.3-beta.0 → 0.20.3-beta.1

package/dist/bridge/bridge-main.js

@@ -4059,6 +4059,7 @@ var init_session = __esm(() => {
       `Switch to it with /use ${alias}, or remove it first with /session rm ${alias}.`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `The requested name "${desiredAlias}" is already in use (by an archived session). Creating the new session as "${finalAlias}" instead.`,
     sessionAttachNotFound: (alias, agent, workspace) => [
       "No existing session found to attach.",
       `Check the session name and retry: /session attach ${alias} --agent ${agent} --ws ${workspace} --name <session-name>`
@@ -5184,6 +5185,7 @@ var init_session2 = __esm(() => {
       `发送 /use ${alias} 切换到它，或先执行 /session rm ${alias} 删除后再创建。`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `你指定的会话名「${desiredAlias}」已被其他会话（含已睡眠/归档）占用，已自动改为「${finalAlias}」创建。`,
     sessionAttachNotFound: (alias, agent2, workspace2) => [
       "没有找到可绑定的已有会话。",
       `请确认会话名是否正确，然后重新执行：/session attach ${alias} --agent ${agent2} --ws ${workspace2} --name <会话名>`

package/dist/cli.js

@@ -97,6 +97,7 @@ var init_session = __esm(() => {
       `Switch to it with /use ${alias}, or remove it first with /session rm ${alias}.`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `The requested name "${desiredAlias}" is already in use (by an archived session). Creating the new session as "${finalAlias}" instead.`,
     sessionAttachNotFound: (alias, agent, workspace) => [
       "No existing session found to attach.",
       `Check the session name and retry: /session attach ${alias} --agent ${agent} --ws ${workspace} --name <session-name>`
@@ -1222,6 +1223,7 @@ var init_session2 = __esm(() => {
       `发送 /use ${alias} 切换到它，或先执行 /session rm ${alias} 删除后再创建。`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `你指定的会话名「${desiredAlias}」已被其他会话（含已睡眠/归档）占用，已自动改为「${finalAlias}」创建。`,
     sessionAttachNotFound: (alias, agent2, workspace2) => [
       "没有找到可绑定的已有会话。",
       `请确认会话名是否正确，然后重新执行：/session attach ${alias} --agent ${agent2} --ws ${workspace2} --name <会话名>`
@@ -41205,20 +41207,19 @@ async function handleSessions(context, chatKey) {
 async function handleSessionNew(context, chatKey, alias, agent3, workspace3, model) {
   const channelId = getChannelIdFromChatKey(chatKey);
   const internalAlias = scopeDisplayAliasToInternal(channelId, alias);
-  const existing = context.sessions.getResolvedSessionByInternalAlias(internalAlias);
-  if (existing) {
-    return { text: t().session.sessionAlreadyExists(alias, existing.agent, existing.workspace) };
-  }
-  const releaseAliasReservation = context.sessions.tryReserveNewSessionAlias(internalAlias);
-  if (!releaseAliasReservation) {
+  const reserved = context.sessions.tryReserveFreeSessionAlias(internalAlias);
+  if (!reserved) {
     const claimed = context.sessions.getResolvedSessionByInternalAlias(internalAlias);
     return {
       text: claimed ? t().session.sessionAlreadyExists(alias, claimed.agent, claimed.workspace) : t().session.sessionAlreadyExists(alias, agent3, workspace3)
     };
   }
+  const { alias: finalInternalAlias, release: releaseAliasReservation } = reserved;
+  const finalDisplayAlias = toDisplaySessionAlias(finalInternalAlias);
+  const aliasWasAdjusted = finalInternalAlias !== internalAlias;
   try {
-    const stableTransportSession = `${workspace3}:${internalAlias}`;
-    const session3 = context.lifecycle.resolveSession(internalAlias, agent3, workspace3, context.sessions.buildFreshTransportSession(stableTransportSession));
+    const stableTransportSession = `${workspace3}:${finalInternalAlias}`;
+    const session3 = context.lifecycle.resolveSession(finalInternalAlias, agent3, workspace3, context.sessions.buildFreshTransportSession(stableTransportSession));
     const normalizedModel = model?.trim();
     if (normalizedModel) {
       session3.model = normalizedModel;
@@ -41234,18 +41235,27 @@ async function handleSessionNew(context, chatKey, alias, agent3, workspace3, mod
       } catch (error2) {
         return context.recovery.renderSessionCreationError(session3, error2);
       }
-      await context.sessions.attachSession(internalAlias, agent3, workspace3, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
+      await context.sessions.attachSession(finalInternalAlias, agent3, workspace3, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
       if (normalizedModel) {
-        await context.sessions.setSessionModel(internalAlias, normalizedModel);
+        await context.sessions.setSessionModel(finalInternalAlias, normalizedModel);
       }
-      await context.sessions.useSession(chatKey, internalAlias);
-      await refreshSessionTransportAgentCommandBestEffort(context, internalAlias, "session.agent_command_refresh_failed");
+      await context.sessions.useSession(chatKey, finalInternalAlias);
+      await refreshSessionTransportAgentCommandBestEffort(context, finalInternalAlias, "session.agent_command_refresh_failed");
       await context.logger.info("session.created", "created and selected logical session", {
-        alias: internalAlias,
+        alias: finalInternalAlias,
         agent: agent3,
         workspace: workspace3
       });
-      return { text: t().session.sessionCreated(alias) };
+      if (aliasWasAdjusted) {
+        return {
+          text: [
+            t().session.sessionAliasCollided(alias, finalDisplayAlias),
+            t().session.sessionCreated(finalDisplayAlias)
+          ].join(`
+`)
+        };
+      }
+      return { text: t().session.sessionCreated(finalDisplayAlias) };
     } finally {
       await releaseTransportReservation();
     }
@@ -42845,65 +42855,67 @@ async function handleSessionShortcutCommand(context, ops, chatKey, agent3, targe
   const baseAlias = `${workspace3.name}:${agent3}`;
   const channelId = getChannelIdFromChatKey(chatKey);
   const scopedBase = scopeDisplayAliasToInternal(channelId, baseAlias);
-  const alias = createNew ? await allocateUniqueSessionAlias(context, scopedBase, chatKey) : scopedBase;
-  const display = toDisplaySessionAlias(alias);
-  if (!createNew && await hasLogicalSession(context, alias, chatKey)) {
-    await context.sessions.useSession(chatKey, alias);
+  const desiredAlias = scopedBase;
+  const desiredDisplay = toDisplaySessionAlias(desiredAlias);
+  if (!createNew && await hasLogicalSession(context, desiredAlias, chatKey)) {
+    await context.sessions.useSession(chatKey, desiredAlias);
     await context.logger.info("session.shortcut.reused", "reused existing logical session", {
-      alias,
+      alias: desiredAlias,
       workspace: workspace3.name,
       agent: agent3
     });
     return {
       text: [
-        t().shortcut.reuseHeader(display),
+        t().shortcut.reuseHeader(desiredDisplay),
         t().shortcut.reuseWorkspace(workspace3.name),
-        t().shortcut.reuseSession(display)
+        t().shortcut.reuseSession(desiredDisplay)
       ].join(`
 `)
     };
   }
-  const releaseAliasReservation = context.sessions.tryReserveNewSessionAlias(alias);
-  if (!releaseAliasReservation) {
-    return renderShortcutSessionCreationError(workspace3, display);
+  const reserved = context.sessions.tryReserveFreeSessionAlias(desiredAlias);
+  if (!reserved) {
+    return renderShortcutSessionCreationError(workspace3, desiredDisplay);
   }
+  const { alias: finalAlias, release: releaseAliasReservation } = reserved;
+  const finalDisplay = toDisplaySessionAlias(finalAlias);
   try {
-    const stableTransportSession = channelId === "weixin" ? alias : context.sessions.buildDefaultTransportSessionForChat(chatKey, display);
-    const session3 = ops.resolveSession(alias, agent3, workspace3.name, context.sessions.buildFreshTransportSession(stableTransportSession));
+    const stableTransportSession = channelId === "weixin" ? finalAlias : context.sessions.buildDefaultTransportSessionForChat(chatKey, finalDisplay);
+    const session3 = ops.resolveSession(finalAlias, agent3, workspace3.name, context.sessions.buildFreshTransportSession(stableTransportSession));
     const releaseTransportReservation = await ops.reserveTransportSession(stableTransportSession);
     try {
       try {
         await ops.ensureTransportSession(session3);
         const exists = await ops.checkTransportSession(session3);
         if (!exists) {
-          return renderShortcutSessionCreationError(workspace3, display);
+          return renderShortcutSessionCreationError(workspace3, finalDisplay);
         }
       } catch (err) {
         if (err instanceof AutoInstallFailedError)
           throw err;
-        return renderShortcutSessionCreationError(workspace3, display);
+        return renderShortcutSessionCreationError(workspace3, finalDisplay);
       }
-      await context.sessions.attachSession(alias, agent3, workspace3.name, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
-      await context.sessions.useSession(chatKey, alias);
+      await context.sessions.attachSession(finalAlias, agent3, workspace3.name, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
+      await context.sessions.useSession(chatKey, finalAlias);
       try {
-        await ops.refreshSessionTransportAgentCommand(alias);
+        await ops.refreshSessionTransportAgentCommand(finalAlias);
       } catch (error2) {
         await context.logger.error("session.shortcut.agent_command_refresh_failed", "failed to refresh session agent command", {
-          alias,
+          alias: finalAlias,
           error: error2 instanceof Error ? error2.message : String(error2)
         });
       }
       await context.logger.info("session.shortcut.created", "created new logical session from shortcut", {
-        alias,
+        alias: finalAlias,
         workspace: workspace3.name,
         agent: agent3,
         workspaceReused: workspace3.reused
       });
       return {
         text: [
-          t().shortcut.createdHeader(display),
+          t().shortcut.createdHeader(finalDisplay),
           workspace3.reused ? t().shortcut.createdReusedWorkspace(workspace3.name) : t().shortcut.createdNewWorkspace(workspace3.name, workspace3.cwd),
-          t().shortcut.createdNewSession(display)
+          t().shortcut.createdNewSession(finalDisplay)
         ].join(`
 `)
       };
@@ -42950,16 +42962,6 @@ async function resolveShortcutWorkspace(context, target) {
     reused: false
   };
 }
-async function allocateUniqueSessionAlias(context, baseAlias, chatKey) {
-  if (!await hasLogicalSession(context, baseAlias, chatKey)) {
-    return baseAlias;
-  }
-  let suffix = 2;
-  while (await hasLogicalSession(context, `${baseAlias}-${suffix}`, chatKey)) {
-    suffix += 1;
-  }
-  return `${baseAlias}-${suffix}`;
-}
 async function hasLogicalSession(context, alias, chatKey) {
   const sessions = await context.sessions.listSessions(chatKey);
   return sessions.some((session3) => session3.internalAlias === alias);
@@ -43082,17 +43084,43 @@ async function attachNativeSession(context, chatKey, target, session3, alias) {
   const existing = await context.sessions.findAttachedNativeSession(chatKey, nativeTarget.agent, session3.sessionId);
   if (existing) {
     await context.sessions.useSession(chatKey, existing.alias);
-    const displayAlias2 = toDisplaySessionAlias(existing.alias);
+    const displayAlias = toDisplaySessionAlias(existing.alias);
     return {
-      text: t().nativeSession.alreadySwitched(nativeTarget.agentDisplayName, displayAlias2)
+      text: t().nativeSession.alreadySwitched(nativeTarget.agentDisplayName, displayAlias)
     };
   }
+  const channelId = getChannelIdFromChatKey(chatKey);
   const requestedAlias = alias?.trim() || buildDefaultNativeAlias(nativeTarget.agent, session3.sessionId);
-  const displayAlias = await allocateUniqueNativeAlias(context, chatKey, requestedAlias);
-  const internalAlias = scopeDisplayAliasToInternal(getChannelIdFromChatKey(chatKey), displayAlias);
-  const transportSession = context.sessions.buildDefaultTransportSessionForChat(chatKey, displayAlias);
-  const resolvedSession = context.lifecycle.resolveSession(internalAlias, nativeTarget.agent, nativeTarget.workspace, transportSession);
-  const releaseReservation = await context.lifecycle.reserveTransportSession(resolvedSession.transportSession);
+  let reserved = null;
+  let finalDisplayAlias = requestedAlias;
+  for (let attempt = 0;attempt < 5; attempt += 1) {
+    const candidateDisplay = await allocateUniqueNativeAlias(context, chatKey, requestedAlias);
+    const candidateInternal = scopeDisplayAliasToInternal(channelId, candidateDisplay);
+    const release = context.sessions.tryReserveNewSessionAlias(candidateInternal);
+    if (release) {
+      reserved = { alias: candidateInternal, release };
+      finalDisplayAlias = candidateDisplay;
+      break;
+    }
+  }
+  let finalInternalAlias;
+  let releaseAliasReservation;
+  if (reserved) {
+    finalInternalAlias = reserved.alias;
+    releaseAliasReservation = reserved.release;
+  } else {
+    const desiredInternal = scopeDisplayAliasToInternal(channelId, finalDisplayAlias);
+    const free = context.sessions.tryReserveFreeSessionAlias(desiredInternal);
+    if (!free) {
+      return { text: t().session.sessionAlreadyExists(finalDisplayAlias, nativeTarget.agent, nativeTarget.workspace) };
+    }
+    finalInternalAlias = free.alias;
+    releaseAliasReservation = free.release;
+    finalDisplayAlias = toDisplaySessionAlias(finalInternalAlias);
+  }
+  const transportSession = context.sessions.buildDefaultTransportSessionForChat(chatKey, finalDisplayAlias);
+  const resolvedSession = context.lifecycle.resolveSession(finalInternalAlias, nativeTarget.agent, nativeTarget.workspace, transportSession);
+  const releaseTransportReservation = await context.lifecycle.reserveTransportSession(resolvedSession.transportSession);
   try {
     try {
       await context.transport.resumeAgentSession(resolvedSession, session3.sessionId);
@@ -43104,7 +43132,7 @@ async function attachNativeSession(context, chatKey, target, session3, alias) {
       return { text: t().nativeSession.attachVerificationFailed(target.agentDisplayName) };
     }
     await context.sessions.attachNativeSession({
-      alias: internalAlias,
+      alias: finalInternalAlias,
       agent: nativeTarget.agent,
       workspace: nativeTarget.workspace,
       transportSession,
@@ -43115,13 +43143,17 @@ async function attachNativeSession(context, chatKey, target, session3, alias) {
       title: session3.title,
       updatedAt: session3.updatedAt
     });
-    await context.sessions.useSession(chatKey, internalAlias);
-    await refreshAgentCommandBestEffort(context, internalAlias);
+    await context.sessions.useSession(chatKey, finalInternalAlias);
+    await refreshAgentCommandBestEffort(context, finalInternalAlias);
     return {
-      text: t().nativeSession.attachedAndSwitched(target.agentDisplayName, toDisplaySessionAlias(internalAlias))
+      text: t().nativeSession.attachedAndSwitched(target.agentDisplayName, toDisplaySessionAlias(finalInternalAlias))
     };
   } finally {
-    await releaseReservation();
+    try {
+      await releaseTransportReservation();
+    } finally {
+      releaseAliasReservation();
+    }
   }
 }
 async function resolveNativeTarget(context, chatKey, input) {
@@ -44384,13 +44416,14 @@ class SessionControlService {
     this.reserveLogicalTransportSession = deps.reserveLogicalTransportSession;
   }
   async createSessionWithTransport(internalAlias, agent3, workspace3, model) {
-    const releaseAliasReservation = this.sessions.tryReserveNewSessionAlias(internalAlias);
-    if (!releaseAliasReservation) {
-      throw new Error(`session "${internalAlias}" already exists`);
+    const reserved = this.sessions.tryReserveFreeSessionAlias(internalAlias);
+    if (!reserved) {
+      throw new Error(`session "${internalAlias}" already exists and could not derive a free alias`);
     }
+    const { alias: finalInternalAlias, release: releaseAliasReservation } = reserved;
     try {
-      const stableTransportSession = `${workspace3}:${internalAlias}`;
-      const session3 = this.sessions.resolveSession(internalAlias, agent3, workspace3, this.sessions.buildFreshTransportSession(stableTransportSession));
+      const stableTransportSession = `${workspace3}:${finalInternalAlias}`;
+      const session3 = this.sessions.resolveSession(finalInternalAlias, agent3, workspace3, this.sessions.buildFreshTransportSession(stableTransportSession));
       const normalizedModel = model?.trim();
       if (normalizedModel) {
         session3.model = normalizedModel;
@@ -44402,15 +44435,15 @@ class SessionControlService {
         if (!exists) {
           throw new Error(`transport session "${session3.transportSession}" could not be verified`);
         }
-        await this.sessions.attachSession(internalAlias, agent3, workspace3, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
+        await this.sessions.attachSession(finalInternalAlias, agent3, workspace3, session3.transportSession, session3.agentCommand, session3.acpxAgent, session3.agentArgv);
         if (normalizedModel) {
-          await this.sessions.setSessionModel(internalAlias, normalizedModel);
+          await this.sessions.setSessionModel(finalInternalAlias, normalizedModel);
         }
         try {
-          await this.invoker.refreshSessionTransportAgentCommand(internalAlias);
+          await this.invoker.refreshSessionTransportAgentCommand(finalInternalAlias);
         } catch (error2) {
           await this.logger.error("session.agent_command_refresh_failed", "failed to refresh session agent command", {
-            alias: internalAlias,
+            alias: finalInternalAlias,
             error: error2 instanceof Error ? error2.message : String(error2)
           });
         }
@@ -44533,12 +44566,13 @@ class SessionControlService {
     if (!this.transport.resumeAgentSession) {
       throw new Error("the active transport does not support native sessions");
     }
-    const releaseAliasReservation = this.sessions.tryReserveNewSessionAlias(internalAlias);
-    if (!releaseAliasReservation) {
-      throw new Error(`session "${internalAlias}" already exists`);
+    const reserved = this.sessions.tryReserveFreeSessionAlias(internalAlias);
+    if (!reserved) {
+      throw new Error(`session "${internalAlias}" already exists and could not derive a free alias`);
     }
+    const { alias: finalInternalAlias, release: releaseAliasReservation } = reserved;
     try {
-      const session3 = this.sessions.resolveSession(internalAlias, agent3, workspace3, `${workspace3}:${internalAlias}`);
+      const session3 = this.sessions.resolveSession(finalInternalAlias, agent3, workspace3, `${workspace3}:${finalInternalAlias}`);
       const release = await this.reserveLogicalTransportSession(session3.transportSession);
       try {
         await this.transport.resumeAgentSession(session3, agentSessionId);
@@ -44547,7 +44581,7 @@ class SessionControlService {
           throw new Error(`transport session "${session3.transportSession}" could not be verified`);
         }
         await this.sessions.attachNativeSession({
-          alias: internalAlias,
+          alias: finalInternalAlias,
           agent: agent3,
           workspace: workspace3,
           transportSession: session3.transportSession,
@@ -44559,10 +44593,10 @@ class SessionControlService {
           ...nativeMeta?.updatedAt !== undefined ? { updatedAt: nativeMeta.updatedAt } : {}
         });
         try {
-          await this.invoker.refreshSessionTransportAgentCommand(internalAlias);
+          await this.invoker.refreshSessionTransportAgentCommand(finalInternalAlias);
         } catch (error2) {
           await this.logger.error("session.native.agent_command_refresh_failed", "failed to refresh native session agent command", {
-            alias: internalAlias,
+            alias: finalInternalAlias,
             error: error2 instanceof Error ? error2.message : String(error2)
           });
         }
@@ -49832,6 +49866,37 @@ class SessionService {
       this.pendingSessionAliasOperations.delete(alias);
     };
   }
+  deriveFreeAlias(desiredAlias) {
+    const taken = Object.keys(this.state.sessions);
+    const takenSet = new Set(taken);
+    if (!takenSet.has(desiredAlias))
+      return desiredAlias;
+    const sep4 = desiredAlias.lastIndexOf(":");
+    const prefix = sep4 >= 0 ? desiredAlias.slice(0, sep4 + 1) : "";
+    const base = sep4 >= 0 ? desiredAlias.slice(sep4 + 1) : desiredAlias;
+    const suffixMatch = /-(\d+)$/.exec(base);
+    let startN = 2;
+    let stem = base;
+    if (suffixMatch) {
+      startN = Number(suffixMatch[1]) + 1;
+      stem = base.slice(0, -suffixMatch[0].length);
+    }
+    for (let n = startN;n <= 9999; n += 1) {
+      const candidate = `${prefix}${stem}-${n}`;
+      if (!takenSet.has(candidate))
+        return candidate;
+    }
+    throw new Error(`could not derive a free alias for "${desiredAlias}" after 9999 attempts`);
+  }
+  tryReserveFreeSessionAlias(desiredAlias) {
+    for (let attempt = 0;attempt < 5; attempt += 1) {
+      const alias = this.deriveFreeAlias(desiredAlias);
+      const release = this.tryReserveNewSessionAlias(alias);
+      if (release)
+        return { alias, release };
+    }
+    return null;
+  }
   buildFreshTransportSession(stableTransportSession) {
     const timestamp = Math.max(0, Math.trunc(this.now()));
     const nonce = randomBytes2(8).readBigUInt64BE().toString().padStart(20, "0");
@@ -57056,7 +57121,8 @@ class ControlService {
     const session3 = agentSessionId ? await this.deps.attachNativeSessionWithTransport(internalAlias, agent3, workspace3, agentSessionId) : await this.deps.createSessionWithTransport(internalAlias, agent3, workspace3, model);
     this.deps.events.emit({ type: "sessions-changed" });
     if (nativeHistory.length > 0) {
-      this.deps.events.emit({ type: "session-history", chatKey, sessionAlias: alias, messages: nativeHistory });
+      const historyAlias = toDisplaySessionAlias(session3.alias);
+      this.deps.events.emit({ type: "session-history", chatKey, sessionAlias: historyAlias, messages: nativeHistory });
     }
     return {
       alias: toDisplaySessionAlias(session3.alias),

package/dist/i18n/types.d.ts

@@ -12,6 +12,7 @@ export interface SessionMessages {
     sessionListItem: (alias: string, agent: string, workspace: string) => string;
     sessionCreated: (alias: string) => string;
     sessionAlreadyExists: (alias: string, agent: string, workspace: string) => string;
+    sessionAliasCollided: (desiredAlias: string, finalAlias: string) => string;
     sessionAttachNotFound: (alias: string, agent: string, workspace: string) => string;
     sessionAttached: (alias: string) => string;
     sessionLifecycleBusy: (alias: string) => string;

package/dist/plugin-api.js

@@ -97,6 +97,7 @@ var init_session = __esm(() => {
       `Switch to it with /use ${alias}, or remove it first with /session rm ${alias}.`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `The requested name "${desiredAlias}" is already in use (by an archived session). Creating the new session as "${finalAlias}" instead.`,
     sessionAttachNotFound: (alias, agent, workspace) => [
       "No existing session found to attach.",
       `Check the session name and retry: /session attach ${alias} --agent ${agent} --ws ${workspace} --name <session-name>`
@@ -1222,6 +1223,7 @@ var init_session2 = __esm(() => {
       `发送 /use ${alias} 切换到它，或先执行 /session rm ${alias} 删除后再创建。`
     ].join(`
 `),
+    sessionAliasCollided: (desiredAlias, finalAlias) => `你指定的会话名「${desiredAlias}」已被其他会话（含已睡眠/归档）占用，已自动改为「${finalAlias}」创建。`,
     sessionAttachNotFound: (alias, agent2, workspace2) => [
       "没有找到可绑定的已有会话。",
       `请确认会话名是否正确，然后重新执行：/session attach ${alias} --agent ${agent2} --ws ${workspace2} --name <会话名>`

package/dist/sessions/session-service.d.ts

@@ -124,6 +124,30 @@ export declare class SessionService {
     tryReserveNewSessionAlias(alias: string): (() => void) | null;
     /** Exclusively claim any lifecycle operation that can replace an alias binding. */
     tryReserveSessionAliasOperation(alias: string): (() => void) | null;
+    /**
+     * Derive a free internal alias for a new session. When `desiredAlias` is already
+     * taken (by an active OR archived session), append `-2`, `-3`, … until a free
+     * slot is found.
+     *
+     * The alias may carry a channel prefix (`relay:demo`, `weixin:chat123/demo`); the
+     * numeric suffix is always appended to the last path segment after the rightmost
+     * `:` so prefix semantics are preserved (e.g. `relay:demo-2`, never `relay-2:demo`).
+     */
+    deriveFreeAlias(desiredAlias: string): string;
+    /**
+     * Convenience: atomically derive a free alias (see `deriveFreeAlias`) AND
+     * reserve it via `tryReserveNewSessionAlias`. If the derived alias loses the
+     * race between the derive step and the reserve step (extremely rare because
+     * callers typically run this while holding the state mutex), retry up to a
+     * small, bounded number of times.
+     *
+     * Returns the chosen alias together with the reservation release callback, or
+     * `null` if no reservation could be obtained.
+     */
+    tryReserveFreeSessionAlias(desiredAlias: string): {
+        alias: string;
+        release: () => void;
+    } | null;
     /**
      * Allocate a fresh acpx transport incarnation while preserving a stable logical
      * coordinator identity. Explicit "new session" paths use this; archive/restore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.20.3-beta.0",
+  "version": "0.20.3-beta.1",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",