@ganglion/xacpx 0.20.3 → 0.22.0

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）`,
@@ -4690,7 +4692,9 @@ var LOCAL_AGENT_BINS;
 var init_local_agent_bin = __esm(() => {
   LOCAL_AGENT_BINS = {
     opencode: { bin: "opencode", args: ["acp"] },
-    kilocode: { bin: "kilocode", args: ["acp"] }
+    kilocode: { bin: "kilocode", args: ["acp"] },
+    reasonix: { bin: "reasonix", args: ["acp"] },
+    omp: { bin: "omp", args: ["acp"] }
   };
 });
 
@@ -6721,6 +6725,9 @@ var init_agent_templates = __esm(() => {
     mux: {
       driver: "mux"
     },
+    omp: {
+      driver: "omp"
+    },
     opencode: {
       driver: "opencode"
     },
@@ -6733,6 +6740,9 @@ var init_agent_templates = __esm(() => {
     qwen: {
       driver: "qwen"
     },
+    reasonix: {
+      driver: "reasonix"
+    },
     trae: {
       driver: "trae"
     },
@@ -8203,7 +8213,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 +8311,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 +29383,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 +29636,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 +29646,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 +29730,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 +29795,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 +29833,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 +29865,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));
@@ -30404,6 +30449,27 @@ var init_plugin_home = __esm(() => {
 import { spawn as spawn8 } from "node:child_process";
 import { rm as rm6 } from "node:fs/promises";
 import { join as join15 } from "node:path";
+function pluginRegistryInstallArgs(registry2 = effectivePluginRegistry()) {
+  return [
+    `--registry=${registry2}`,
+    `--@ganglion:registry=${registry2}`
+  ];
+}
+function effectivePluginRegistry(env = process.env) {
+  const raw = coreEnv("PLUGIN_REGISTRY", env)?.trim();
+  if (!raw)
+    return DEFAULT_PLUGIN_REGISTRY;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error("XACPX_PLUGIN_REGISTRY must be a valid http(s) URL");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || !url.hostname) {
+    throw new Error("XACPX_PLUGIN_REGISTRY must be a valid http(s) URL");
+  }
+  return url.toString().replace(/\/+$/, "");
+}
 function shellSpawnPlan(args) {
   const shell = process.platform === "win32";
   return { shell, args: shell ? args.map((arg) => `"${arg}"`) : args };
@@ -30454,11 +30520,12 @@ async function installPluginPackage(input) {
     await rm6(join15(input.pluginHome, "bun.lock"), { force: true }).catch(() => {});
   }
   const spec = input.version ? `${input.packageName}@${input.version}` : input.packageName;
+  const registryArgs = pluginRegistryInstallArgs();
   if (packageManager === "bun") {
-    await runCommand("bun", ["add", spec], { cwd: input.pluginHome });
+    await runCommand("bun", ["add", spec, ...registryArgs], { cwd: input.pluginHome });
     return;
   }
-  await runCommand("npm", ["install", spec], { cwd: input.pluginHome });
+  await runCommand("npm", ["install", spec, ...registryArgs], { cwd: input.pluginHome });
 }
 async function updatePluginPackage(input) {
   await installPluginPackage(input);
@@ -30472,6 +30539,7 @@ async function removePluginPackage(input) {
   }
   await runCommand("npm", ["uninstall", input.packageName], { cwd: input.pluginHome });
 }
+var DEFAULT_PLUGIN_REGISTRY = "https://registry.npmjs.org";
 var init_package_manager = __esm(() => {
   init_plugin_home();
 });
@@ -32272,7 +32340,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 +32443,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 +32466,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 +36456,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 +36480,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 +36500,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 +36984,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 +37004,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 +38460,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 +38499,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 +38871,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 +38915,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 +49743,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 +49755,7 @@ class SessionService {
   platform;
   runtimeRoot;
   pendingSessionAliasOperations = new Set;
+  lifecyclePublisher;
   constructor(config4, stateStore, state, options = {}) {
     this.config = config4;
     this.stateStore = stateStore;
@@ -49667,6 +49801,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 +49875,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 nextState = structuredClone(this.state);
+        const result2 = this.applyUseSession(nextState, chatKey, internalAlias);
+        await this.commitLifecycleTransition(nextState);
+        this.publishLifecycleEvent("restored", nextState.sessions[internalAlias]);
+        return result2;
       }
-      const nextCtx = { ...prevCtx, current_session: internalAlias };
-      if (carriedPrevious) {
-        nextCtx.previous_session = carriedPrevious;
-      } else {
-        delete nextCtx.previous_session;
-      }
-      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 +50074,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 +50158,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 +50197,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 +50220,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 +50482,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 +50532,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 +50876,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 +50951,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 +56813,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 +56857,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 +57660,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 +57771,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 +58517,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 +58633,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 +58654,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 +59002,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 +59275,7 @@ async function buildApp(paths, deps = {}) {
     agent: agent3,
     router: router3,
     sessions,
+    sessionResources,
     activeTurns,
     stateStore,
     configStore,
@@ -59144,6 +59412,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 +59613,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 +59779,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 +61502,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 +61551,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 +61635,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 +61681,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 +62026,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 +62349,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 +62579,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 };