@ganglion/xacpx 0.20.3 → 0.21.0

package/dist/bridge/bridge-main.js

@@ -4889,6 +4889,7 @@ var init_channel_cli = __esm(() => {
     channelAdded: (type) => `Channel ${type} added`,
     cannotRemoveLastEnabled: "Cannot remove the last enabled channel.",
     channelRemoved: (id) => `Channel ${id} removed`,
+    channelRetirementFailed: (id, error) => `Channel ${id} retirement cleanup failed: ${error}`,
     channelCredentialsCleared: (id) => `Removed stored credentials for channel ${id}`,
     channelCredentialsClearFailed: (id, error) => `Channel ${id} removed, but clearing its stored credentials failed: ${error}`,
     channelCredentialsKept: (id) => `Kept stored credentials for channel ${id} (--keep-credentials)`,
@@ -6015,6 +6016,7 @@ var init_channel_cli2 = __esm(() => {
     channelAdded: (type) => `频道 ${type} 已添加`,
     cannotRemoveLastEnabled: "不能删除最后一个启用的频道。",
     channelRemoved: (id) => `频道 ${id} 已删除`,
+    channelRetirementFailed: (id, error) => `频道 ${id} 退役清理失败：${error}`,
     channelCredentialsCleared: (id) => `已移除频道 ${id} 的存储凭证`,
     channelCredentialsClearFailed: (id, error) => `频道 ${id} 已删除，但清除其存储凭证失败：${error}`,
     channelCredentialsKept: (id) => `已保留频道 ${id} 的存储凭证（--keep-credentials）`,

package/dist/channels/cli/provider.d.ts

@@ -22,6 +22,18 @@ export interface ChannelCliIo {
     promptText: (message: string) => Promise<string>;
     promptSecret: (message: string) => Promise<string>;
 }
+/**
+ * Structured doctor finding from an optional channel/plugin diagnostic hook.
+ * Core renders these verbatim and must not interpret RMUX-specific codes.
+ */
+export type ChannelDoctorFindingLevel = "ok" | "warn" | "error" | "skip";
+export interface ChannelDoctorFinding {
+    level: ChannelDoctorFindingLevel;
+    code: string;
+    message: string;
+    suggestion?: string;
+    details?: Record<string, string | number | boolean | null>;
+}
 export interface ChannelCliProvider {
     type: string;
     displayName: string;
@@ -31,6 +43,11 @@ export interface ChannelCliProvider {
     validateConfig(config: ChannelRuntimeConfig): ChannelCliValidationIssue[];
     renderSummary(config: ChannelRuntimeConfig): string[];
     promptForMissingFields(input: ChannelCliInput, io: ChannelCliIo): Promise<ChannelCliInput>;
+    /**
+     * Optional read-only health probe for `xacpx doctor` / `xacpx plugin doctor`.
+     * Must not mutate registry, credentials, or kill resources.
+     */
+    diagnose?(config: ChannelRuntimeConfig): Promise<ChannelDoctorFinding[]> | ChannelDoctorFinding[];
     /**
      * Optional: declares this plugin supports the `xacpx channel ... --account <id>`
      * multi-bot CLI surface. Plugins that opt in must also implement

package/dist/channels/plugin.d.ts

@@ -1,9 +1,30 @@
 import type { ChannelFactory } from "./create-channel.js";
 import type { ChannelCliProvider } from "./cli/provider.js";
+import type { ChannelRuntimeConfig } from "../config/types.js";
+export type ChannelRetireDaemonState = "running" | "stopped" | "indeterminate";
+/** Context passed to a plugin `retireChannel` hook from `channel disable|rm`. */
+export interface ChannelRetireContext {
+    channel: ChannelRuntimeConfig;
+    reason: "disabled" | "removed";
+    print: (line: string) => void;
+    getDaemonStatus: () => Promise<{
+        state: ChannelRetireDaemonState;
+    }>;
+}
+export type ChannelRetireHook = (ctx: ChannelRetireContext) => Promise<void>;
 export interface ChannelPluginDefinition {
     /** Stable channel type used in channels[].type and chatKey prefix. */
     type: string;
     factory: ChannelFactory;
     cliProvider?: ChannelCliProvider;
+    /**
+     * Optional CLI lifecycle hook for `xacpx channel disable|rm`.
+     * Invoked after plugins are loaded, via the per-type registry — core must
+     * not import the plugin npm package to retire resources.
+     */
+    retireChannel?: ChannelRetireHook;
 }
 export declare function registerChannelPlugin(plugin: ChannelPluginDefinition): void;
+export declare function getChannelRetireHook(type: string): ChannelRetireHook | undefined;
+/** Dispatch `channel disable|rm` retirement to the loaded plugin for this type. */
+export declare function invokeChannelRetireHook(ctx: ChannelRetireContext): Promise<void>;

package/dist/channels/types.d.ts

@@ -5,6 +5,7 @@ import type { AppLogger } from "../logging/app-logger.js";
 import type { PendingFinalChunk } from "../weixin/messaging/quota-manager.js";
 import type { PerfTracer } from "../perf/perf-tracer.js";
 import type { SessionService } from "../sessions/session-service.js";
+import type { SessionResourceCatalog } from "../sessions/session-resource-catalog.js";
 import type { ActiveTurnRegistry } from "../sessions/active-turn-registry.js";
 import type { Locale } from "../i18n/index.js";
 import type { ControlService } from "../control/control-service.js";
@@ -79,6 +80,12 @@ export interface ChannelStartInput {
      * channels ignore it.
      */
     control?: ControlService;
+    /**
+     * Generic catalog of logical-session resources: immutable logical session
+     * IDs, internal/display aliases, authoritative workspace cwd, archived flag,
+     * and a lifecycle-event subscription. Optional: text-only channels ignore it.
+     */
+    sessionResources?: SessionResourceCatalog;
 }
 export interface OrchestrationDeliveryCallbacks {
     markTaskNoticeDelivered: (taskId: string, accountId: string) => Promise<void>;
@@ -114,6 +121,7 @@ export interface ConsumerLockOptions {
     lockFilePath?: string;
     onDiagnostic?: (event: string, context: Record<string, string | number | boolean | undefined>) => void | Promise<void>;
 }
+export type ChannelStopReason = "shutdown" | "disabled" | "removed" | "logout";
 export interface MessageChannelRuntime {
     id: string;
     isLoggedIn(): boolean;
@@ -122,15 +130,21 @@ export interface MessageChannelRuntime {
      * Destructive credential removal. Reached only via the explicit
      * `xacpx logout` CLI path — never as part of a normal shutdown.
      */
-    logout(): void;
+    logout(): void | Promise<void>;
     start(input: ChannelStartInput): Promise<void>;
     /**
      * Non-destructive shutdown: release runtime resources without touching
      * stored credentials. Optional for compatibility with already-published
      * plugin channels; when absent, the registry falls back to `logout()`
      * (which for those plugins is a benign client stop).
+     *
+     * @param reason - The reason for stopping:
+     *   - "shutdown": normal signal/startup-error cleanup
+     *   - "disabled": channel disabled via CLI
+     *   - "removed": channel removed via CLI
+     *   - "logout": explicit logout command
      */
-    stop?(): void | Promise<void>;
+    stop?(reason?: ChannelStopReason): void | Promise<void>;
     createConsumerLock?(options?: ConsumerLockOptions): ConsumerLock;
     configureOrchestration?(callbacks: OrchestrationDeliveryCallbacks): void;
     notifyTaskCompletion(task: OrchestrationTaskRecord): Promise<void>;

package/dist/cli.js

@@ -927,6 +927,7 @@ var init_channel_cli = __esm(() => {
     channelAdded: (type) => `Channel ${type} added`,
     cannotRemoveLastEnabled: "Cannot remove the last enabled channel.",
     channelRemoved: (id) => `Channel ${id} removed`,
+    channelRetirementFailed: (id, error) => `Channel ${id} retirement cleanup failed: ${error}`,
     channelCredentialsCleared: (id) => `Removed stored credentials for channel ${id}`,
     channelCredentialsClearFailed: (id, error) => `Channel ${id} removed, but clearing its stored credentials failed: ${error}`,
     channelCredentialsKept: (id) => `Kept stored credentials for channel ${id} (--keep-credentials)`,
@@ -2053,6 +2054,7 @@ var init_channel_cli2 = __esm(() => {
     channelAdded: (type) => `频道 ${type} 已添加`,
     cannotRemoveLastEnabled: "不能删除最后一个启用的频道。",
     channelRemoved: (id) => `频道 ${id} 已删除`,
+    channelRetirementFailed: (id, error) => `频道 ${id} 退役清理失败：${error}`,
     channelCredentialsCleared: (id) => `已移除频道 ${id} 的存储凭证`,
     channelCredentialsClearFailed: (id, error) => `频道 ${id} 已删除，但清除其存储凭证失败：${error}`,
     channelCredentialsKept: (id) => `已保留频道 ${id} 的存储凭证（--keep-credentials）`,
@@ -8203,7 +8205,7 @@ function createCoreRuntimeLock(options) {
         try {
           if (isBunRuntime() && !options.loadFsExt) {
             await handle.close();
-            posixHelper = await acquireFlockHelper(options.lockFilePath, options.helperAcquireTimeoutMs, options.helperHandshakeDelayMs);
+            posixHelper = await acquireFlockHelper(options.lockFilePath, options.helperAcquireTimeoutMs, options.helperHandshakeDelayMs, onDiagnostic);
             await emitDiagnostic(onDiagnostic, "lock_helper_started", {
               lockFilePath: options.lockFilePath,
               helperPid: posixHelper.pid
@@ -8301,11 +8303,17 @@ async function releasePosixLock(options, handle, helper) {
 function isBunRuntime() {
   return Boolean(globalThis.Bun);
 }
-async function acquireFlockHelper(lockFilePath, timeoutMs = 1e4, handshakeDelayMs = 0) {
+async function acquireFlockHelper(lockFilePath, timeoutMs = 1e4, handshakeDelayMs = 0, onDiagnostic) {
   const fsExtPath = require2.resolve("fs-ext");
   const child = spawn7("node", ["-e", FLOCK_HELPER_SOURCE, fsExtPath, lockFilePath, String(handshakeDelayMs)], {
     stdio: ["pipe", "pipe", "pipe"]
   });
+  if (child.pid) {
+    await emitDiagnostic(onDiagnostic, "lock_helper_spawned", {
+      lockFilePath,
+      helperPid: child.pid
+    });
+  }
   const line = await new Promise((resolve5, reject) => {
     let stdout = "";
     let stderr = "";
@@ -29367,6 +29375,7 @@ function createEmptyState() {
 var init_types4 = () => {};
 
 // src/state/state-store.ts
+import { randomUUID as randomUUID6 } from "node:crypto";
 import { readFile as readFile10, rename as rename3, writeFile as writeFile4 } from "node:fs/promises";
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -29619,6 +29628,9 @@ function parseOrchestrationState(raw, dropped) {
 function isReplyMode2(value) {
   return value === "stream" || value === "final" || value === "verbose";
 }
+function isLogicalSessionId(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
 function isSessionSource(value) {
   return value === undefined || value === "weacpx" || value === "xacpx" || value === "agent-side";
 }
@@ -29626,16 +29638,26 @@ function isSessionRecord(value) {
   if (!isRecord3(value)) {
     return false;
   }
-  return isString(value.alias) && isString(value.agent) && isString(value.workspace) && isString(value.transport_session) && isSessionSource(value.source) && isOptionalString(value.agent_session_id) && isOptionalString(value.agent_session_title) && isOptionalString(value.agent_session_updated_at) && isOptionalString(value.attached_at) && isOptionalString(value.transport_agent_command) && isOptionalString(value.transport_acpx_agent) && (value.transport_agent_argv === undefined || isStringArray(value.transport_agent_argv)) && isOptionalString(value.mode_id) && isOptionalString(value.effort) && (value.reply_mode === undefined || isReplyMode2(value.reply_mode)) && isString(value.created_at) && isString(value.last_used_at);
+  return isString(value.alias) && isString(value.agent) && isString(value.workspace) && isString(value.transport_session) && (value.logical_session_id === undefined || isLogicalSessionId(value.logical_session_id)) && isSessionSource(value.source) && isOptionalString(value.agent_session_id) && isOptionalString(value.agent_session_title) && isOptionalString(value.agent_session_updated_at) && isOptionalString(value.attached_at) && isOptionalString(value.transport_agent_command) && isOptionalString(value.transport_acpx_agent) && (value.transport_agent_argv === undefined || isStringArray(value.transport_agent_argv)) && isOptionalString(value.mode_id) && isOptionalString(value.effort) && (value.reply_mode === undefined || isReplyMode2(value.reply_mode)) && isString(value.created_at) && isString(value.last_used_at);
 }
-function parseSessions(raw, dropped) {
+function parseSessions(raw, dropped, migrated) {
   const sessions = {};
   for (const [alias, value] of Object.entries(raw)) {
     if (!isSessionRecord(value)) {
       dropped.push({ section: "sessions", key: alias, reason: "malformed session record" });
       continue;
     }
-    sessions[alias] = value;
+    if (value.logical_session_id === undefined) {
+      migrated.push({
+        section: "sessions",
+        key: alias,
+        reason: "legacy record missing logical_session_id; assigned a new UUIDv4"
+      });
+    }
+    sessions[alias] = {
+      ...value,
+      logical_session_id: value.logical_session_id ?? randomUUID6()
+    };
   }
   return sessions;
 }
@@ -29700,11 +29722,11 @@ function parseScheduledTasks(raw, dropped) {
   }
   return tasks;
 }
-function parseState(raw, path3, dropped = []) {
+function parseState(raw, path3, dropped = [], migrated = []) {
   if (!isRecord3(raw)) {
     throw new Error(`state file "${path3}" must contain a JSON object`);
   }
-  const parsedSessions = parseSessions(sectionRecord(raw.sessions, "sessions", dropped), dropped);
+  const parsedSessions = parseSessions(sectionRecord(raw.sessions, "sessions", dropped), dropped, migrated);
   const orchestration3 = parseOrchestrationState(raw.orchestration, dropped);
   repairExternalCoordinatorIdentityCollisions(parsedSessions, orchestration3, dropped);
   return {
@@ -29765,20 +29787,31 @@ class StateStore {
     if (read.kind === "corrupt") {
       return await this.recoverFromCorruptFile(read.reason);
     }
-    if (read.dropped.length === 0) {
+    if (read.dropped.length === 0 && read.migrated.length === 0) {
       return read.state;
     }
     const report = { dropped: read.dropped };
-    const quarantinePath = `${this.path}.quarantine-${this.fileTimestamp()}`;
-    try {
-      const written = await (this.options.writeBackup ?? defaultWriteBackup)(quarantinePath, read.content);
-      report.quarantinePath = typeof written === "string" ? written : quarantinePath;
-    } catch (error2) {
-      report.backupError = error2 instanceof Error ? error2.message : String(error2);
+    if (read.migrated.length > 0) {
+      report.migrated = read.migrated;
+    }
+    if (read.dropped.length > 0) {
+      const quarantinePath = `${this.path}.quarantine-${this.fileTimestamp()}`;
+      try {
+        const written = await (this.options.writeBackup ?? defaultWriteBackup)(quarantinePath, read.content);
+        report.quarantinePath = typeof written === "string" ? written : quarantinePath;
+      } catch (error2) {
+        report.backupError = error2 instanceof Error ? error2.message : String(error2);
+      }
+    }
+    if (read.migrated.length > 0) {
+      await this.persistMigration(read.state);
     }
     this.loadReport = report;
     return read.state;
   }
+  async persistMigration(state) {
+    await (this.options.writeMigration ?? ((next) => this.save(next)))(state);
+  }
   async inspect() {
     const read = await this.readAndParse();
     if (read.kind === "absent") {
@@ -29792,7 +29825,10 @@ class StateStore {
     }
     return {
       state: read.state,
-      report: read.dropped.length > 0 ? { dropped: read.dropped } : null
+      report: read.dropped.length > 0 || read.migrated.length > 0 ? {
+        dropped: read.dropped,
+        ...read.migrated.length > 0 ? { migrated: read.migrated } : {}
+      } : null
     };
   }
   async readAndParse() {
@@ -29821,7 +29857,8 @@ class StateStore {
       return { kind: "corrupt", reason: "top-level value is not an object" };
     }
     const dropped = [];
-    return { kind: "parsed", state: parseState(parsed, this.path, dropped), dropped, content };
+    const migrated = [];
+    return { kind: "parsed", state: parseState(parsed, this.path, dropped, migrated), dropped, migrated, content };
   }
   async save(state) {
     await writePrivateFileAtomic(this.path, JSON.stringify({ version: STATE_FILE_VERSION, ...state }, null, 2));
@@ -32272,7 +32309,7 @@ var require_main = __commonJS((exports, module) => {
 });
 
 // src/weixin/auth/login-qr.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomUUID as randomUUID7 } from "node:crypto";
 function isLoginFresh(login3) {
   return Date.now() - login3.startedAt < ACTIVE_LOGIN_TTL_MS;
 }
@@ -32375,7 +32412,7 @@ async function readVerifyCodeFromStdin(prompt) {
   });
 }
 async function startWeixinLoginWithQr(opts) {
-  const sessionKey = opts.accountId || randomUUID6();
+  const sessionKey = opts.accountId || randomUUID7();
   purgeExpiredLogins();
   const existing = activeLogins.get(sessionKey);
   if (!opts.force && existing && isLoginFresh(existing) && existing.qrcodeUrl) {
@@ -32398,7 +32435,7 @@ async function startWeixinLoginWithQr(opts) {
     });
     const login3 = {
       sessionKey,
-      id: randomUUID6(),
+      id: randomUUID7(),
       qrcode: qrResponse.qrcode,
       qrcodeUrl: qrResponse.qrcode_img_content,
       startedAt: Date.now()
@@ -36388,7 +36425,7 @@ var init_scheduled_turn = __esm(() => {
 });
 
 // src/weixin/monitor/consumer-lock.ts
-import { randomUUID as randomUUID7 } from "node:crypto";
+import { randomUUID as randomUUID8 } from "node:crypto";
 import { mkdir as mkdir10, open as open6, readFile as readFile12, rm as rm9, writeFile as writeFile7 } from "node:fs/promises";
 import { dirname as dirname15, join as join17 } from "node:path";
 import { homedir as homedir6 } from "node:os";
@@ -36412,7 +36449,7 @@ function createWeixinConsumerLock(options = {}) {
           const existing = await loadLockMetadata(lockFilePath) ?? meta2;
           throw new ActiveWeixinConsumerLockError(lockFilePath, existing);
         }
-        windowsLockId = meta2.lockId ?? randomUUID7();
+        windowsLockId = meta2.lockId ?? randomUUID8();
         const metadata = {
           ...meta2,
           schemaVersion: 2,
@@ -36432,7 +36469,7 @@ function createWeixinConsumerLock(options = {}) {
         return;
       }
       const requestedIdentity = await (options.probeProcessIdentity ?? probePosixProcessIdentity)(meta2.pid);
-      posixLockId = meta2.lockId ?? randomUUID7();
+      posixLockId = meta2.lockId ?? randomUUID8();
       const requested = requestedIdentity.status === "found" ? { ...meta2, schemaVersion: 2, lockId: posixLockId, processStartedAtMs: requestedIdentity.identity.startedAtMs } : { ...meta2, schemaVersion: 2, lockId: posixLockId };
       while (true) {
         try {
@@ -36916,6 +36953,12 @@ var init_registry = __esm(() => {
 });
 
 // src/channels/plugin.ts
+var exports_plugin = {};
+__export(exports_plugin, {
+  registerChannelPlugin: () => registerChannelPlugin,
+  invokeChannelRetireHook: () => invokeChannelRetireHook,
+  getChannelRetireHook: () => getChannelRetireHook
+});
 function registerChannelPlugin(plugin) {
   bootstrapBuiltinChannelFactories();
   bootstrapBuiltinChannelCliProviders();
@@ -36930,10 +36973,23 @@ function registerChannelPlugin(plugin) {
   registerChannelFactory(plugin.type, plugin.factory);
   if (plugin.cliProvider)
     registerChannelCliProvider(plugin.cliProvider);
+  if (plugin.retireChannel)
+    retireHooks.set(channelType, plugin.retireChannel);
 }
+function getChannelRetireHook(type) {
+  return retireHooks.get(type);
+}
+async function invokeChannelRetireHook(ctx) {
+  const hook = retireHooks.get(ctx.channel.type);
+  if (!hook)
+    return;
+  await hook(ctx);
+}
+var retireHooks;
 var init_plugin = __esm(() => {
   init_create_channel();
   init_registry();
+  retireHooks = new Map;
 });
 
 // src/plugins/compatibility.ts
@@ -38373,6 +38429,13 @@ async function removeChannel(type, rawArgs, deps) {
     deps.print(t().channelCli.cannotRemoveLastEnabled);
     return 1;
   }
+  if (deps.retireChannel) {
+    try {
+      await deps.retireChannel(channel, "removed");
+    } catch (error2) {
+      deps.print(t().channelCli.channelRetirementFailed(channel.id, error2 instanceof Error ? error2.message : String(error2)));
+    }
+  }
   config4.channels = config4.channels.filter((entry) => entry.id !== channel.id);
   await deps.saveChannels(config4.channels);
   deps.print(t().channelCli.channelRemoved(channel.id));
@@ -38405,6 +38468,13 @@ async function setChannelEnabled(type, enabled, rawArgs, deps) {
     deps.print(t().channelCli.cannotDisableLastEnabled);
     return 1;
   }
+  if (!enabled && channel.enabled && deps.retireChannel) {
+    try {
+      await deps.retireChannel(channel, "disabled");
+    } catch (error2) {
+      deps.print(t().channelCli.channelRetirementFailed(channel.id, error2 instanceof Error ? error2.message : String(error2)));
+    }
+  }
   channel.enabled = enabled;
   await deps.saveChannels(config4.channels);
   deps.print(t().channelCli.channelEnabledToggled(channel.id, enabled));
@@ -38770,6 +38840,16 @@ async function inspectPlugins(input) {
         message: configPlugin.enabled ? `plugin is installed and valid; channels: ${channelTypes.length > 0 ? channelTypes.join(", ") : "none"}` : `plugin is installed and valid but disabled; run xacpx plugin enable ${configPlugin.name}`,
         ...configPlugin.enabled ? {} : { suggestion: `xacpx plugin enable ${configPlugin.name}` }
       });
+      if (configPlugin.enabled) {
+        for (const finding of await collectChannelDiagnoseFindings(plugin.channels ?? [], input.config)) {
+          pushIfRelevant({
+            level: finding.level === "skip" ? "ok" : finding.level,
+            plugin: configPlugin.name,
+            message: finding.level === "skip" ? `${finding.code}: ${finding.message}` : `${finding.code}: ${finding.message}`,
+            ...finding.suggestion ? { suggestion: finding.suggestion } : {}
+          });
+        }
+      }
     } catch (error2) {
       const message = error2 instanceof Error ? error2.message : String(error2);
       pushIfRelevant({ level: "error", plugin: configPlugin.name, message });
@@ -38804,6 +38884,28 @@ async function inspectPlugins(input) {
   }
   return issues;
 }
+async function collectChannelDiagnoseFindings(channelDefs, config4) {
+  const findings = [];
+  for (const def of channelDefs) {
+    const diagnose = def.cliProvider?.diagnose;
+    if (!diagnose)
+      continue;
+    const runtimeChannels = (config4.channels ?? []).filter((channel) => channel.type === def.type && channel.enabled !== false);
+    for (const channel of runtimeChannels) {
+      try {
+        const result = await diagnose(channel);
+        findings.push(...result);
+      } catch (error2) {
+        findings.push({
+          level: "error",
+          code: "channel-diagnose-failed",
+          message: `channel ${channel.type} diagnose hook failed: ${error2 instanceof Error ? error2.message : String(error2)}`
+        });
+      }
+    }
+  }
+  return findings;
+}
 var init_plugin_doctor = __esm(() => {
   init_channel_scope();
   init_plugin_loader();
@@ -49610,7 +49712,7 @@ function replaceRuntimeState(target, source) {
 }
 
 // src/sessions/session-service.ts
-import { randomBytes as randomBytes2 } from "node:crypto";
+import { randomBytes as randomBytes2, randomUUID as randomUUID9 } from "node:crypto";
 import { dirname as dirname19 } from "node:path";
 
 class SessionService {
@@ -49622,6 +49724,7 @@ class SessionService {
   platform;
   runtimeRoot;
   pendingSessionAliasOperations = new Set;
+  lifecyclePublisher;
   constructor(config4, stateStore, state, options = {}) {
     this.config = config4;
     this.stateStore = stateStore;
@@ -49667,6 +49770,7 @@ class SessionService {
       agent: agent3,
       workspace: workspace3,
       transport_session: transportSession,
+      logical_session_id: existing?.logical_session_id ?? randomUUID9(),
       transport_agent_command: sameAgentExisting?.transport_agent_command,
       transport_acpx_agent: sameAgentExisting?.transport_acpx_agent,
       transport_agent_argv: sameAgentExisting?.transport_agent_argv,
@@ -49740,30 +49844,42 @@ class SessionService {
       if (!session3) {
         throw new Error(`session "${alias}" does not exist`);
       }
-      const prevCtx = this.state.chat_contexts[chatKey];
-      const previousCurrent = prevCtx?.current_session;
-      const carriedPrevious = previousCurrent && previousCurrent !== internalAlias ? previousCurrent : prevCtx?.previous_session;
-      session3.last_used_at = new Date().toISOString();
       if (session3.archived) {
-        delete session3.archived;
-        delete session3.archived_at;
-      }
-      const nextCtx = { ...prevCtx, current_session: internalAlias };
-      if (carriedPrevious) {
-        nextCtx.previous_session = carriedPrevious;
-      } else {
-        delete nextCtx.previous_session;
+        const nextState = structuredClone(this.state);
+        const result2 = this.applyUseSession(nextState, chatKey, internalAlias);
+        await this.commitLifecycleTransition(nextState);
+        this.publishLifecycleEvent("restored", nextState.sessions[internalAlias]);
+        return result2;
       }
-      this.state.chat_contexts[chatKey] = nextCtx;
+      const result = this.applyUseSession(this.state, chatKey, internalAlias);
       await this.persist();
-      return {
-        alias: toDisplaySessionAlias(session3.alias),
-        agent: session3.agent,
-        workspace: session3.workspace,
-        previousAlias: carriedPrevious ? toDisplaySessionAlias(carriedPrevious) : undefined
-      };
+      return result;
     });
   }
+  applyUseSession(state, chatKey, internalAlias) {
+    const session3 = state.sessions[internalAlias];
+    const prevCtx = state.chat_contexts[chatKey];
+    const previousCurrent = prevCtx?.current_session;
+    const carriedPrevious = previousCurrent && previousCurrent !== internalAlias ? previousCurrent : prevCtx?.previous_session;
+    session3.last_used_at = new Date().toISOString();
+    if (session3.archived) {
+      delete session3.archived;
+      delete session3.archived_at;
+    }
+    const nextCtx = { ...prevCtx, current_session: internalAlias };
+    if (carriedPrevious) {
+      nextCtx.previous_session = carriedPrevious;
+    } else {
+      delete nextCtx.previous_session;
+    }
+    state.chat_contexts[chatKey] = nextCtx;
+    return {
+      alias: toDisplaySessionAlias(session3.alias),
+      agent: session3.agent,
+      workspace: session3.workspace,
+      previousAlias: carriedPrevious ? toDisplaySessionAlias(carriedPrevious) : undefined
+    };
+  }
   async usePreviousSession(chatKey) {
     return await this.mutate(async () => {
       const ctx = this.state.chat_contexts[chatKey];
@@ -49927,6 +50043,12 @@ class SessionService {
   listInternalAliases() {
     return Object.keys(this.state.sessions);
   }
+  getLogicalSessionRecord(alias) {
+    return this.state.sessions[alias] ?? null;
+  }
+  listLogicalSessionRecords() {
+    return Object.values(this.state.sessions);
+  }
   async setCurrentSessionMode(chatKey, modeId) {
     await this.mutate(async () => {
       const currentAlias = this.state.chat_contexts[chatKey]?.current_session;
@@ -50005,20 +50127,37 @@ class SessionService {
     }
     return count;
   }
+  setSessionResourceLifecyclePublisher(publish) {
+    this.lifecyclePublisher = publish;
+  }
+  publishLifecycleEvent(type, record3) {
+    this.lifecyclePublisher?.({ type, record: record3 });
+  }
+  async commitLifecycleTransition(nextState) {
+    await this.stateStore.saveNow(nextState);
+    replaceRuntimeState(this.state, nextState);
+  }
   async setArchived(alias, archived) {
     await this.mutate(async () => {
       const session3 = this.state.sessions[alias];
       if (!session3) {
         throw new Error(`session "${alias}" does not exist`);
       }
+      const wasArchived = session3.archived === true;
+      if (wasArchived === archived) {
+        return;
+      }
+      const nextState = structuredClone(this.state);
+      const nextSession = nextState.sessions[alias];
       if (archived) {
-        session3.archived = true;
-        session3.archived_at = new Date(this.now()).toISOString();
+        nextSession.archived = true;
+        nextSession.archived_at = new Date(this.now()).toISOString();
       } else {
-        delete session3.archived;
-        delete session3.archived_at;
+        delete nextSession.archived;
+        delete nextSession.archived_at;
       }
-      await this.persist();
+      await this.commitLifecycleTransition(nextState);
+      this.publishLifecycleEvent(archived ? "archived" : "restored", nextSession);
     });
   }
   async removeSession(alias) {
@@ -50027,9 +50166,11 @@ class SessionService {
       if (!session3) {
         throw new Error(`session "${alias}" does not exist`);
       }
-      const wasActive = Object.values(this.state.chat_contexts).some((ctx) => ctx.current_session === alias);
-      delete this.state.sessions[alias];
-      for (const [chatKey, ctx] of Object.entries(this.state.chat_contexts)) {
+      const snapshot = structuredClone(session3);
+      const nextState = structuredClone(this.state);
+      const wasActive = Object.values(nextState.chat_contexts).some((ctx) => ctx.current_session === alias);
+      delete nextState.sessions[alias];
+      for (const [chatKey, ctx] of Object.entries(nextState.chat_contexts)) {
         if (ctx.previous_session === alias) {
           delete ctx.previous_session;
         }
@@ -50048,10 +50189,11 @@ class SessionService {
           }
         }
         if (!ctx.current_session && !ctx.previous_session && !ctx.background_results) {
-          delete this.state.chat_contexts[chatKey];
+          delete nextState.chat_contexts[chatKey];
         }
       }
-      await this.persist();
+      await this.commitLifecycleTransition(nextState);
+      this.publishLifecycleEvent("removed", snapshot);
       return { wasActive };
     });
   }
@@ -50309,6 +50451,7 @@ class SessionService {
         agent: agent3,
         workspace: workspace3,
         transport_session: transportSession,
+        logical_session_id: randomUUID9(),
         source: native?.source,
         agent_session_id: native?.agentSessionId,
         agent_session_title: native?.title ?? undefined,
@@ -50358,6 +50501,89 @@ var init_session_service = __esm(() => {
   init_channel_scope();
 });
 
+// src/sessions/session-resource-catalog.ts
+class CoreSessionResourceCatalog {
+  deps;
+  listeners = new Set;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  async resolve(chatKey, alias) {
+    let internalAlias;
+    try {
+      internalAlias = await this.deps.sessions.resolveAliasForChat(chatKey, alias);
+    } catch {
+      return null;
+    }
+    const record3 = this.deps.sessions.getLogicalSessionRecord(internalAlias);
+    if (!record3) {
+      return null;
+    }
+    const channelId = getChannelIdFromChatKey(chatKey);
+    if (!isSessionAliasVisibleInChannel(record3.alias, channelId)) {
+      return null;
+    }
+    return this.toDescriptor(record3);
+  }
+  async list(channelId) {
+    const descriptors = [];
+    for (const record3 of this.deps.sessions.listLogicalSessionRecords()) {
+      if (!isSessionAliasVisibleInChannel(record3.alias, channelId)) {
+        continue;
+      }
+      const descriptor = this.toDescriptor(record3);
+      if (descriptor) {
+        descriptors.push(descriptor);
+      }
+    }
+    return descriptors;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  publishLifecycleEvent(input) {
+    const descriptor = this.toDescriptor(input.record);
+    if (!descriptor) {
+      return;
+    }
+    this.emit({ type: input.type, session: descriptor });
+  }
+  emit(event) {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(event);
+      } catch (error2) {
+        this.deps.logger.error("sessions.resource_catalog.listener_failed", "session resource listener threw; delivery continues", {
+          message: error2 instanceof Error ? error2.message : String(error2),
+          eventType: event.type,
+          internalAlias: event.session.internalAlias
+        }).catch(() => {});
+      }
+    }
+  }
+  toDescriptor(record3) {
+    const workspace3 = this.deps.config.workspaces[record3.workspace];
+    if (!workspace3) {
+      return null;
+    }
+    return {
+      logicalSessionId: record3.logical_session_id,
+      channelId: getChannelIdFromChatKey(record3.alias),
+      internalAlias: record3.alias,
+      displayAlias: toDisplaySessionAlias(record3.alias),
+      workspace: record3.workspace,
+      cwd: workspace3.cwd,
+      archived: record3.archived === true
+    };
+  }
+}
+var init_session_resource_catalog = __esm(() => {
+  init_channel_scope();
+});
+
 // src/sessions/active-turn-registry.ts
 function createActiveTurnRegistry() {
   const byChat = new Map;
@@ -50619,7 +50845,7 @@ async function deleteAcpxSessionFiles(options) {
 var init_acpx_session_files = () => {};
 
 // src/transport/acpx-queue-owner-launcher.ts
-import { createHash as createHash9, randomUUID as randomUUID8 } from "node:crypto";
+import { createHash as createHash9, randomUUID as randomUUID10 } from "node:crypto";
 import { spawn as spawn13 } from "node:child_process";
 import { access as access6, readFile as readFile18, unlink as unlink2 } from "node:fs/promises";
 import { join as join27 } from "node:path";
@@ -50694,7 +50920,7 @@ class AcpxQueueOwnerLauncher {
     this.probeSpawnedProcess = options.probeSpawnedProcess ?? defaultProbeSpawnedProcess;
     this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 1e4;
     this.handshakePollMs = options.handshakePollMs ?? 50;
-    this.uuid = options.uuid ?? randomUUID8;
+    this.uuid = options.uuid ?? randomUUID10;
     this.sleep = options.sleep ?? ((ms) => new Promise((resolve7) => setTimeout(resolve7, ms)));
   }
   async launch(input) {
@@ -56556,7 +56782,7 @@ var init_session_turn_runner = __esm(() => {
 });
 
 // src/control/turn-queue.ts
-import { randomUUID as randomUUID9 } from "node:crypto";
+import { randomUUID as randomUUID11 } from "node:crypto";
 
 class TurnQueue {
   deps;
@@ -56600,7 +56826,7 @@ class TurnQueue {
           if (q.length >= QUEUE_MAX_DEPTH) {
             return { ok: false, errorMessage: "queue-full" };
           }
-          const id = randomUUID9();
+          const id = randomUUID11();
           const item = {
             id,
             text: params.text,
@@ -57403,7 +57629,7 @@ function warmthKey(session3) {
 }
 
 // src/control/terminal-service.ts
-import { randomUUID as randomUUID10 } from "node:crypto";
+import { randomUUID as randomUUID12 } from "node:crypto";
 import { createRequire as createRequire8 } from "node:module";
 import { statSync as statSync4 } from "node:fs";
 import { spawn as spawnPty2 } from "node-pty";
@@ -57514,7 +57740,7 @@ function createTerminalService(deps) {
   return {
     create({ cwd, cols, rows }) {
       const shell = resolveShell({ platform, env: process.env, shellOverride: deps.shell?.() });
-      const terminalId = randomUUID10();
+      const terminalId = randomUUID12();
       const handle = spawn18(shell, [], { name: "xterm-256color", cols, rows, cwd, env: scrubEnv() });
       const session3 = { handle, seq: 0, idleTimer: null, buffer: "", bufBytes: 0, pending: "", pendingBytes: 0, flushTimer: null };
       sessions.set(terminalId, session3);
@@ -58260,7 +58486,7 @@ __export(exports_main, {
   main: () => main,
   buildApp: () => buildApp
 });
-import { randomUUID as randomUUID11 } from "node:crypto";
+import { randomUUID as randomUUID13 } from "node:crypto";
 import { homedir as homedir17 } from "node:os";
 import { dirname as dirname24, join as join35 } from "node:path";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
@@ -58376,6 +58602,14 @@ async function buildApp(paths, deps = {}) {
         message: stateLoadReport.backupError
       });
     }
+    for (const record3 of stateLoadReport.migrated ?? []) {
+      await logger.info("state.session_id_migrated", "assigned a new logical_session_id to a legacy session record", {
+        statePath: paths.statePath,
+        section: record3.section,
+        key: record3.key,
+        reason: record3.reason
+      });
+    }
   }
   const stateMutex = new AsyncMutex;
   const debouncedStateStore = new DebouncedStateStore({
@@ -58389,11 +58623,13 @@ async function buildApp(paths, deps = {}) {
   });
   const runtimeRoot = dirname24(paths.configPath);
   const sessions = new SessionService(config4, debouncedStateStore, state, { stateMutex, runtimeRoot });
+  const sessionResources = new CoreSessionResourceCatalog({ sessions, config: config4, logger });
+  sessions.setSessionResourceLifecyclePublisher((transition) => sessionResources.publishLifecycleEvent(transition));
   const launchIntentCoordinator = new LaunchIntentCoordinator({
     platform: process.platform,
     runtimeRoot,
     configRoot: runtimeRoot,
-    generationId: deps.daemonIdentity?.generationId ?? randomUUID11(),
+    generationId: deps.daemonIdentity?.generationId ?? randomUUID13(),
     ...deps.orphanRegistry ? { registry: deps.orphanRegistry } : {},
     classifyAdapter: (command) => classifyPreinstalledAdapterCommandShape(command),
     resolveAdapter: async (command) => (await validateAndReResolveAdapterCommand(runtimeRoot, command)).agentCommand,
@@ -58735,7 +58971,7 @@ async function buildApp(paths, deps = {}) {
   };
   orchestration3 = new OrchestrationService({
     now: deps.loggerNow ?? (() => new Date),
-    createId: () => randomUUID11(),
+    createId: () => randomUUID13(),
     config: config4,
     loadState: async () => JSON.parse(JSON.stringify(state)),
     saveState: async (nextState) => {
@@ -59008,6 +59244,7 @@ async function buildApp(paths, deps = {}) {
     agent: agent3,
     router: router3,
     sessions,
+    sessionResources,
     activeTurns,
     stateStore,
     configStore,
@@ -59144,6 +59381,7 @@ var init_main = __esm(() => {
   init_scheduled_route_create();
   init_scheduled_route_manage();
   init_session_service();
+  init_session_resource_catalog();
   init_state_store();
   init_acpx_bridge_client();
   init_acpx_bridge_transport();
@@ -59344,6 +59582,7 @@ async function runConsole(paths, deps) {
       abortSignal: shutdownController.signal,
       quota: runtime.quota,
       sessions: runtime.sessions,
+      sessionResources: runtime.sessionResources,
       activeTurns: runtime.activeTurns,
       logger: runtime.logger,
       perfTracer: runtime.perfTracer,
@@ -59509,14 +59748,14 @@ class MessageChannelRegistry {
       throw new Error("all channels failed to start");
     }
   }
-  async stopAll() {
+  async stopAll(reason = "shutdown") {
     let firstError;
     for (const channel of this.channels.values()) {
       try {
         if (channel.stop) {
-          await channel.stop();
+          await channel.stop(reason);
         } else {
-          channel.logout();
+          await channel.logout();
         }
       } catch (error2) {
         firstError ??= error2;
@@ -61232,11 +61471,20 @@ function applyStateInspectionReport(result, report, statePath, daemonRunning, is
   if (!report) {
     return result;
   }
+  const migrated = report.migrated ?? [];
+  const migrationDetails = migrated.map((record3) => `legacy session record ${record3.section}["${record3.key}"]: ${record3.reason} (applied automatically at next daemon startup)`);
+  if (report.dropped.length === 0) {
+    return {
+      ...result,
+      details: [...result.details ?? [], `state path: ${statePath}`, ...migrationDetails]
+    };
+  }
   const fileCorrupt = report.dropped.some((record3) => record3.section === "file");
   const details = [
     ...result.details ?? [],
     `state path: ${statePath}`,
-    ...report.dropped.map((record3) => record3.section === "file" ? `state.json is unreadable: ${record3.reason}` : `invalid state record ${record3.section}["${record3.key}"]: ${record3.reason}`)
+    ...report.dropped.map((record3) => record3.section === "file" ? `state.json is unreadable: ${record3.reason}` : `invalid state record ${record3.section}["${record3.key}"]: ${record3.reason}`),
+    ...migrationDetails
   ];
   return {
     ...result,
@@ -61272,9 +61520,11 @@ function createStateQuarantineFix(statePath, daemonRunning, isDaemonRunning) {
         return { ok: true, message: `state.json was unreadable; renamed to ${report.corruptPath} and reset` };
       }
       const backup = report.quarantinePath ? ` (original backed up to ${report.quarantinePath})` : "";
+      const migratedCount = report.migrated?.length ?? 0;
+      const migration = migratedCount > 0 ? `; assigned logical_session_id to ${migratedCount} legacy session record(s)` : "";
       return {
         ok: true,
-        message: `quarantined ${report.dropped.length} invalid state.json record(s)${backup}`
+        message: `quarantined ${report.dropped.length} invalid state.json record(s)${backup}${migration}`
       };
     }
   };
@@ -61354,7 +61604,7 @@ __export(exports_cli, {
   getUsageText: () => getUsageText,
   createMcpStdioIdentityResolver: () => createMcpStdioIdentityResolver
 });
-import { randomUUID as randomUUID12 } from "node:crypto";
+import { randomUUID as randomUUID14 } from "node:crypto";
 import { homedir as homedir23 } from "node:os";
 import { dirname as dirname26, join as join39, sep as sep6 } from "node:path";
 import { fileURLToPath as fileURLToPath8 } from "node:url";
@@ -61400,7 +61650,7 @@ async function prepareMcpCoordinatorStartup(input) {
   return { kind: "external-coordinator" };
 }
 function createMcpStdioIdentityResolver(input) {
-  const instanceId = randomUUID12().slice(0, 8);
+  const instanceId = randomUUID14().slice(0, 8);
   return async (context) => {
     const parsedCoordinatorSession = input.parsedCoordinatorSession?.trim() || null;
     const workspace3 = input.workspace?.trim() || null;
@@ -61745,6 +61995,10 @@ function warnStateLoadReport(store, writeStderr = (text) => process.stderr.write
   }
   if (report.backupError) {
     writeStderr(`[xacpx] state.quarantine_backup_failed ${report.backupError}
+`);
+  }
+  for (const record3 of report.migrated ?? []) {
+    writeStderr(`[xacpx] state.session_id_migrated section=${record3.section}${record3.key ? ` key=${record3.key}` : ""} reason=${record3.reason}
 `);
   }
 }
@@ -62064,7 +62318,7 @@ async function defaultLogin() {
 }
 async function defaultLogout() {
   const channel = await resolveLoginChannelForCli();
-  channel.logout();
+  await channel.logout();
 }
 async function defaultLoadConfiguredPluginsForChannelCli() {
   const store = await createCliConfigStore();
@@ -62294,7 +62548,23 @@ async function createChannelCliDeps(input) {
     restartDaemon: async () => await restartDaemonCli(controller, input.print),
     clearChannelCredentials: async (channel) => {
       const { createMessageChannel: createMessageChannel2 } = await Promise.resolve().then(() => (init_create_channel(), exports_create_channel));
-      createMessageChannel2(channel.type, channel).logout();
+      await createMessageChannel2(channel.type, channel).logout();
+    },
+    retireChannel: async (channel, reason) => {
+      const { invokeChannelRetireHook: invokeChannelRetireHook2 } = await Promise.resolve().then(() => (init_plugin(), exports_plugin));
+      await invokeChannelRetireHook2({
+        channel,
+        reason,
+        print: input.print,
+        getDaemonStatus: async () => {
+          const status = await controller.getStatus();
+          if (status.state === "running")
+            return { state: "running" };
+          if (status.state === "indeterminate")
+            return { state: "indeterminate" };
+          return { state: "stopped" };
+        }
+      });
     }
   };
   return { ...base, ...input.overrides };

package/dist/i18n/types.d.ts

@@ -700,6 +700,7 @@ export interface ChannelCliMessages {
     channelAdded: (type: string) => string;
     cannotRemoveLastEnabled: string;
     channelRemoved: (id: string) => string;
+    channelRetirementFailed: (id: string, error: string) => string;
     channelCredentialsCleared: (id: string) => string;
     channelCredentialsClearFailed: (id: string, error: string) => string;
     channelCredentialsKept: (id: string) => string;

package/dist/plugin-api.d.ts

@@ -1,9 +1,9 @@
-export type { ChannelPluginDefinition } from "./channels/plugin.js";
+export type { ChannelPluginDefinition, ChannelRetireContext, ChannelRetireDaemonState, ChannelRetireHook, } from "./channels/plugin.js";
 export type { ChannelFactory, CreateChannelDeps } from "./channels/create-channel.js";
-export type { ChannelStartInput, ConsumerLock, ConsumerLockMetadata, ConsumerLockOptions, CoordinatorMessageInput, MessageChannelRuntime, ScheduledChannelMessageInput, OrchestrationDeliveryCallbacks, OutboundQuota, PlanEntry, PlanEntryStatus, ToolUseEvent, ToolUseKind, ToolUseStatus, } from "./channels/types.js";
+export type { ChannelStartInput, ConsumerLock, ConsumerLockMetadata, ConsumerLockOptions, ChannelStopReason, CoordinatorMessageInput, MessageChannelRuntime, ScheduledChannelMessageInput, OrchestrationDeliveryCallbacks, OutboundQuota, PlanEntry, PlanEntryStatus, ToolUseEvent, ToolUseKind, ToolUseStatus, } from "./channels/types.js";
 export { formatSubagentNotice, SubagentNoticeTracker } from "./channels/subagent-notice.js";
 export type { AgentCommand, PromptUsage, UsageBreakdown, UsageCost, } from "./transport/types.js";
-export type { ChannelCliInput, ChannelCliIo, ChannelCliParseResult, ChannelCliProvider, ChannelCliValidationIssue, } from "./channels/cli/provider.js";
+export type { ChannelCliInput, ChannelCliIo, ChannelCliParseResult, ChannelCliProvider, ChannelCliValidationIssue, ChannelDoctorFinding, ChannelDoctorFindingLevel, } from "./channels/cli/provider.js";
 export type { ChannelRuntimeConfig } from "./config/types.js";
 export type { CommandHint } from "./commands/command-hints.js";
 export type { AppLogger } from "./logging/app-logger.js";
@@ -22,4 +22,5 @@ export { getLocale } from "./i18n/index.js";
 export type { Locale } from "./i18n/index.js";
 export type { ControlExecuteCommandInput, ControlPromptInput, ControlPromptResult, ControlService, ControlSessionInfo, } from "./control/control-service.js";
 export type { ControlEvent, ControlEventBus, ControlEventListener } from "./control/control-event-bus.js";
+export type { SessionResourceCatalog, SessionResourceDescriptor, SessionResourceLifecycleEvent, } from "./sessions/session-resource-catalog.js";
 export { coreHomeDir } from "./runtime/core-home.js";

package/dist/plugin-api.js

@@ -927,6 +927,7 @@ var init_channel_cli = __esm(() => {
     channelAdded: (type) => `Channel ${type} added`,
     cannotRemoveLastEnabled: "Cannot remove the last enabled channel.",
     channelRemoved: (id) => `Channel ${id} removed`,
+    channelRetirementFailed: (id, error) => `Channel ${id} retirement cleanup failed: ${error}`,
     channelCredentialsCleared: (id) => `Removed stored credentials for channel ${id}`,
     channelCredentialsClearFailed: (id, error) => `Channel ${id} removed, but clearing its stored credentials failed: ${error}`,
     channelCredentialsKept: (id) => `Kept stored credentials for channel ${id} (--keep-credentials)`,
@@ -2053,6 +2054,7 @@ var init_channel_cli2 = __esm(() => {
     channelAdded: (type) => `频道 ${type} 已添加`,
     cannotRemoveLastEnabled: "不能删除最后一个启用的频道。",
     channelRemoved: (id) => `频道 ${id} 已删除`,
+    channelRetirementFailed: (id, error) => `频道 ${id} 退役清理失败：${error}`,
     channelCredentialsCleared: (id) => `已移除频道 ${id} 的存储凭证`,
     channelCredentialsClearFailed: (id, error) => `频道 ${id} 已删除，但清除其存储凭证失败：${error}`,
     channelCredentialsKept: (id) => `已保留频道 ${id} 的存储凭证（--keep-credentials）`,

package/dist/sessions/session-resource-catalog.d.ts

@@ -0,0 +1,96 @@
+import type { AppConfig } from "../config/types";
+import type { AppLogger } from "../logging/app-logger";
+import type { LogicalSession } from "../state/types";
+import type { SessionService } from "./session-service";
+/**
+ * A point-in-time snapshot of one logical session's resource identity. The
+ * immutable `logicalSessionId` is the ONLY stable key: aliases, display names
+ * and transport bindings can all change under the same id. `cwd` is resolved
+ * authoritatively from the core workspace config — callers (e.g. browsers)
+ * never contribute a cwd. Descriptors are snapshots: a previously returned
+ * descriptor never mutates when the underlying session changes.
+ */
+export interface SessionResourceDescriptor {
+    logicalSessionId: string;
+    channelId: string;
+    internalAlias: string;
+    displayAlias: string;
+    workspace: string;
+    cwd: string;
+    archived: boolean;
+}
+export type SessionResourceLifecycleEvent = {
+    type: "archived";
+    session: SessionResourceDescriptor;
+} | {
+    type: "restored";
+    session: SessionResourceDescriptor;
+} | {
+    type: "removed";
+    session: SessionResourceDescriptor;
+};
+/**
+ * Write-side seam handed to SessionService: after a lifecycle transition has
+ * been durably persisted (never before), the service reports the transition
+ * type plus the persisted record; the catalog maps the record to a descriptor
+ * and publishes the event to subscribers. For `removed` the record is the
+ * pre-delete snapshot, so the event carries the session's final identity.
+ */
+export interface SessionResourceLifecyclePublishInput {
+    type: SessionResourceLifecycleEvent["type"];
+    record: LogicalSession;
+}
+/**
+ * Generic, channel-agnostic catalog over logical session resources. Contains
+ * no channel- or consumer-specific vocabulary; structured channels (and their
+ * plugins) use it to enumerate and resolve the sessions they own.
+ */
+export interface SessionResourceCatalog {
+    /**
+     * Resolve a chat-scoped alias (display or internal form) to a descriptor.
+     * Uses the same chat-scope resolution as ControlService: a caller can never
+     * reach another channel's sessions. Returns null for unknown aliases and
+     * for sessions whose workspace is no longer registered (their cwd cannot be
+     * authoritatively resolved).
+     */
+    resolve(chatKey: string, alias: string): Promise<SessionResourceDescriptor | null>;
+    /** All sessions of one channel, active AND archived, for reconciliation. */
+    list(channelId: string): Promise<SessionResourceDescriptor[]>;
+    /**
+     * Register a lifecycle listener; returns an unsubscribe function. Listener
+     * exceptions are caught and logged to the app log: they never roll back the
+     * underlying session operation and never block other listeners.
+     */
+    subscribe(listener: (event: SessionResourceLifecycleEvent) => void): () => void;
+}
+interface SessionResourceCatalogDeps {
+    sessions: SessionService;
+    config: AppConfig;
+    logger: AppLogger;
+}
+/**
+ * Production catalog assembled by the core runtime over the live SessionService
+ * and workspace config. Plugin/channel tests should use their own in-memory
+ * implementation of the interface instead of this adapter.
+ */
+export declare class CoreSessionResourceCatalog implements SessionResourceCatalog {
+    private readonly deps;
+    private readonly listeners;
+    constructor(deps: SessionResourceCatalogDeps);
+    resolve(chatKey: string, alias: string): Promise<SessionResourceDescriptor | null>;
+    list(channelId: string): Promise<SessionResourceDescriptor[]>;
+    subscribe(listener: (event: SessionResourceLifecycleEvent) => void): () => void;
+    /**
+     * Publish one durably-persisted lifecycle transition. SessionService calls
+     * this (via the publisher it was handed at runtime wiring) strictly AFTER
+     * saveNow succeeded and the runtime state was published; the catalog itself
+     * never persists anything. Records whose workspace is no longer registered
+     * produce no event: such sessions are invisible in resolve()/list(), so
+     * consumers never tracked a resource for them.
+     */
+    publishLifecycleEvent(input: SessionResourceLifecyclePublishInput): void;
+    /** Fan an event out to all subscribers; listener throws are isolated. */
+    private emit;
+    private toDescriptor;
+}
+export {};

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

@@ -1,7 +1,8 @@
 import type { AppConfig } from "../config/types";
 import { AsyncMutex } from "../orchestration/async-mutex";
 import type { StateStore } from "../state/state-store";
-import type { AppState, BackgroundResult } from "../state/types";
+import type { AppState, BackgroundResult, LogicalSession } from "../state/types";
+import type { SessionResourceLifecyclePublishInput } from "./session-resource-catalog";
 import type { AgentSession, ResolvedSession } from "../transport/types";
 interface SessionListItem {
     alias: string;
@@ -79,6 +80,7 @@ export declare class SessionService {
     private readonly platform;
     private readonly runtimeRoot;
     private readonly pendingSessionAliasOperations;
+    private lifecyclePublisher;
     constructor(config: AppConfig, stateStore: SessionStateWriter, state: AppState, options?: SessionServiceOptions);
     createSession(alias: string, agent: string, workspace: string): Promise<ResolvedSession>;
     /**
@@ -109,6 +111,8 @@ export declare class SessionService {
     getPreferredSessionForTransport(transportSession: string): Promise<ResolvedSession | null>;
     findAttachedNativeSession(chatKey: string, agent: string, agentSessionId: string): Promise<ResolvedSession | null>;
     useSession(chatKey: string, alias: string): Promise<SessionSwitchResult>;
+    /** Apply the use-session mutation (switch, plus restore when archived). */
+    private applyUseSession;
     usePreviousSession(chatKey: string): Promise<SessionSwitchResult | null>;
     setBackgroundResult(chatKey: string, alias: string, result: BackgroundResult): Promise<void>;
     takeBackgroundResult(chatKey: string, alias: string): Promise<BackgroundResult | null>;
@@ -155,11 +159,36 @@ export declare class SessionService {
      */
     buildFreshTransportSession(stableTransportSession: string): string;
     listInternalAliases(): string[];
+    /**
+     * Read-only access to the persisted logical session record by internal alias.
+     * Returns the LIVE record — callers must treat it as immutable. Exists for
+     * consumers (the session resource catalog) that need fields ResolvedSession
+     * does not carry (immutable logical_session_id, archived flag).
+     */
+    getLogicalSessionRecord(alias: string): LogicalSession | null;
+    /** Read-only view of every persisted logical session record, across all channels. */
+    listLogicalSessionRecords(): LogicalSession[];
     setCurrentSessionMode(chatKey: string, modeId: string | undefined): Promise<void>;
     setCurrentSessionReplyMode(chatKey: string, replyMode: "stream" | "final" | "verbose" | undefined): Promise<void>;
     getCurrentSession(chatKey: string): Promise<ResolvedSession | null>;
     listSessions(chatKey: string): Promise<SessionListItem[]>;
     countAliasesSharingTransport(transportSession: string, excludeAlias?: string): number;
+    /**
+     * Wire the sink for resource lifecycle events (production: the core
+     * SessionResourceCatalog; the runtime calls this once after constructing
+     * the catalog). Archive/restore/remove transitions report through it only
+     * AFTER their state has been durably persisted — never before.
+     */
+    setSessionResourceLifecyclePublisher(publish: (input: SessionResourceLifecyclePublishInput) => void): void;
+    private publishLifecycleEvent;
+    /**
+     * Durability gate for lifecycle transitions: persist the copy-on-write
+     * snapshot first (saveNow rejects on write failure, so the live state, chat
+     * contexts and event stream all stay untouched), then publish the persisted
+     * snapshot to the runtime state. Only after this resolves may the lifecycle
+     * event be emitted.
+     */
+    private commitLifecycleTransition;
     setArchived(alias: string, archived: boolean): Promise<void>;
     removeSession(alias: string): Promise<{
         wasActive: boolean;

package/dist/state/state-store.d.ts

@@ -12,6 +12,12 @@ export interface StateLoadDroppedRecord {
 }
 export interface StateLoadReport {
     dropped: StateLoadDroppedRecord[];
+    /**
+     * Legacy session records that were assigned a fresh logical_session_id
+     * during load. Kept separate from {@link dropped}: a migrated record is
+     * healthy and survives, a dropped record is corrupt and was removed.
+     */
+    migrated?: StateLoadDroppedRecord[];
     /** Backup copy of the original file, written because records were dropped. */
     quarantinePath?: string;
     /** Unreadable original renamed aside (whole-file JSON corruption). */
@@ -19,6 +25,12 @@ export interface StateLoadReport {
     /** Best-effort backup/rename failure; load still returned the cleaned state. */
     backupError?: string;
 }
+/**
+ * A logical_session_id is always a UUIDv4 (randomUUID). Present-but-invalid
+ * values are treated as corruption and quarantined with the record; only a
+ * genuinely MISSING field (legacy record) enters the load-time migration.
+ */
+export declare function isLogicalSessionId(value: unknown): value is string;
 /**
  * Lenient state parser: a malformed record (or wrong-typed section) is skipped
  * and collected in `dropped` instead of throwing, so one bad record can never
@@ -27,7 +39,7 @@ export interface StateLoadReport {
  * non-object top level still throws (StateStore.load treats that as a corrupt
  * file and renames it aside).
  */
-export declare function parseState(raw: unknown, path: string, dropped?: StateLoadDroppedRecord[]): AppState;
+export declare function parseState(raw: unknown, path: string, dropped?: StateLoadDroppedRecord[], migrated?: StateLoadDroppedRecord[]): AppState;
 export interface StateStoreOptions {
     /** Injectable clock used for quarantine/corrupt backup file names. */
     now?: () => Date;
@@ -37,6 +49,11 @@ export interface StateStoreOptions {
      * writer suffix-retries instead of overwriting an existing backup).
      */
     writeBackup?: (targetPath: string, content: string) => Promise<string | void>;
+    /**
+     * Injectable durable writer for the legacy logical_session_id migration
+     * (tests simulate write failures). Defaults to the regular atomic save.
+     */
+    writeMigration?: (state: AppState) => Promise<void>;
 }
 /** Result of a side-effect-free {@link StateStore.inspect}. */
 export interface StateLoadInspection {
@@ -56,11 +73,13 @@ export declare class StateStore {
      */
     get lastLoadReport(): StateLoadReport | null;
     load(): Promise<AppState>;
+    /** Synchronous (awaited) atomic write of a migrated state, via the private-file writer. */
+    private persistMigration;
     /**
      * Side-effect-free variant of load() for diagnostic callers (doctor): parses
-     * and reports exactly what load() would drop/repair, but never writes a
-     * quarantine backup, never renames a corrupt file, and does not touch
-     * {@link lastLoadReport}.
+     * and reports exactly what load() would drop/repair/migrate, but never writes
+     * a quarantine backup, never renames a corrupt file, never persists pending
+     * logical_session_id migrations, and does not touch {@link lastLoadReport}.
      */
     inspect(): Promise<StateLoadInspection>;
     private readAndParse;

package/dist/state/types.d.ts

@@ -20,6 +20,14 @@ export interface LogicalSession {
     agent: string;
     workspace: string;
     transport_session: string;
+    /**
+     * Immutable identity of this logical session (UUIDv4), assigned once at
+     * create/attach time. Never changes across rename, display-name, agent,
+     * workspace, or transport-binding updates; never reused after the alias is
+     * deleted. Legacy records missing the field are migrated once at load time
+     * and persisted before startup proceeds.
+     */
+    logical_session_id: string;
     source?: LogicalSessionSource;
     agent_session_id?: string;
     agent_session_title?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",
@@ -54,6 +54,7 @@
     "build:relay": "bun run build:relay-web && bun run clean:relay && bun build ./packages/relay/src/cli.ts --outdir ./packages/relay/dist --target node --external ws --external hono --external @hono/node-server --external @ganglion/xacpx-relay-protocol && tsc -p packages/relay/tsconfig.json && bun run bundle:relay-web",
     "clean:channel-relay": "node -e \"require('node:fs').rmSync('packages/channel-relay/dist', { recursive: true, force: true })\"",
     "build:channel-relay": "bun run build:plugin-api && bun run build:relay-protocol && bun run clean:channel-relay && bun build ./packages/channel-relay/src/index.ts --outdir ./packages/channel-relay/dist --target node --external xacpx --external ws --external @ganglion/xacpx-relay-protocol && tsc -p packages/channel-relay/tsconfig.json",
+    "pack:rmux-bridge": "node ./scripts/pack-rmux-bridge-platform.mjs",
     "clean:relay-web": "node -e \"require('node:fs').rmSync('packages/relay-web/dist',{recursive:true,force:true})\"",
     "build:relay-web": "bun run build:relay-protocol && bun run clean:relay-web && bun run --cwd packages/relay-web build",
     "test:web": "bun run --cwd packages/relay-web test",