@xmanrui/dsh-im 4.21.2 → 4.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmanrui/dsh-im",
-  "version": "4.21.2",
+  "version": "4.22.0",
   "description": "把十一种 IM 渠道和公网 AI Office 接入本机 DeepSeek Harness。 Connect eleven IM channels and a public AI Office to a local DeepSeek Harness.",
   "keywords": [
     "deepseek-harness",
@@ -114,6 +114,7 @@
     "src",
     "PROACTIVE_DELIVERY.md",
     "PROACTIVE_DELIVERY.en.md",
+    "docs/client-integration.md",
     "LICENSE",
     "README.md",
     "README.en.md",

package/plugin-src/client/i18n.js

@@ -39,6 +39,7 @@ const EN = Object.freeze({
   'macOS Messages 权限': 'macOS Messages permissions',
   'IM机器人': 'IM bots',
   'IM机器人设置': 'IM bot settings',
+  'IM 面板加载失败': 'Could not load the IM panel',
   '更多机器人设置': 'More bot settings',
   '机器人设置': 'Bot settings',
   '机器人设置页签': 'Bot settings tabs',

package/plugin-src/client/index.js

@@ -74,6 +74,7 @@ import { installImStyles } from './styles.js';
 import { installSessionChannelLogos } from './session-channel-logos.js';
 import { UpdatePanel, UPDATE_RPC_CHANNEL } from './update-panel.js';
 import { WorkspaceDirectoryPickerContext } from './workspace-editor.js';
+import { IMPanelErrorBoundary } from './panel-error-boundary.js';
 
 export const name = 'im-settings';
 export const inject = ['slots', 'connection', 'locale', 'workspaces'];
@@ -209,10 +210,15 @@ export function IMSettingsTab({
   deliveryRpcCall,
   globalSettingsRpcCall,
   workspaceDirectoryPicker,
+  preferredSectionId,
   browserLocation = globalThis.location,
   navigateToRecoveryUrl = replacePageLocation,
 }) {
-  const [selected, setSelected] = React.useState('weixin');
+  const [selected, setSelected] = React.useState(() => (
+    preferredSectionId === GLOBAL_SETTINGS_TAB_ID
+      || CHANNELS.some((channel) => channel.id === preferredSectionId)
+      ? preferredSectionId : 'weixin'
+  ));
   const [loopbackRecovery, setLoopbackRecovery] = React.useState(null);
   const [runningVersion, setRunningVersion] = React.useState(IM_PLUGIN_VERSION);
   const [deliverySettings, setDeliverySettings] = React.useState(null);
@@ -471,29 +477,89 @@ export function apply(ctx) {
     pickDirectory: () => callWorkspaceDirectoryApi(ctx, 'pickDirectory'),
   });
 
-  ctx.slots.inject('settings.section', () => ctx.slots.register({
-    name: 'settings.section',
-    id: 'xmanrui-dsh-im',
-    order: 21,
-    label: () => t('IM机器人'),
-    locale: IM_LOCALE_NAMESPACE,
-    inject: () => ({
-      dingtalkRpcCall,
-      discordRpcCall,
-      feishuRpcCall,
-      qqRpcCall,
-      slackRpcCall,
-      telegramRpcCall,
-      wecomRpcCall,
-      wecomAppRpcCall,
-      weixinRpcCall,
-      whatsappRpcCall,
-      imessageRpcCall,
-      officeRpcCall,
-      updateRpcCall,
-      deliveryRpcCall,
-      globalSettingsRpcCall,
-      workspaceDirectoryPicker,
-    }),
-  }, IMSettingsTab));
+  const panelDependencies = {
+    dingtalkRpcCall,
+    discordRpcCall,
+    feishuRpcCall,
+    qqRpcCall,
+    slackRpcCall,
+    telegramRpcCall,
+    wecomRpcCall,
+    wecomAppRpcCall,
+    weixinRpcCall,
+    whatsappRpcCall,
+    imessageRpcCall,
+    officeRpcCall,
+    updateRpcCall,
+    deliveryRpcCall,
+    globalSettingsRpcCall,
+    workspaceDirectoryPicker,
+  };
+  const subscribeLocale = (listener) => typeof ctx.on === 'function'
+    ? ctx.on('locale/change', listener) : () => {};
+  const localeSnapshot = () => ctx.locale.getLocale?.()?.active ?? '';
+
+  // Stable for this plugin lifetime: creating an element must not create a
+  // new component type and reset the reader's selected tab or unsaved input.
+  function IMPanel({ preferredSectionId }) {
+    React.useSyncExternalStore(subscribeLocale, localeSnapshot, localeSnapshot);
+    return h(IMPanelErrorBoundary, null,
+      h(IMSettingsTab, { ...panelDependencies, preferredSectionId }));
+  }
+  const buildPanelElement = (props = {}) => h(IMPanel, {
+    preferredSectionId: props.preferredSectionId,
+  });
+
+  ctx.effect(() => {
+    let disposed = false;
+    let stopSettings = null;
+    let registered = false;
+    const setSettingsVisible = (visible) => {
+      if (disposed) return;
+      if (typeof visible !== 'boolean') throw new TypeError('visible must be a boolean');
+      if (visible === (stopSettings !== null)) return;
+      if (!visible) {
+        const stop = stopSettings;
+        stopSettings = null;
+        stop();
+        return;
+      }
+      // The existing slot controller owns late declarations, withdrawal and
+      // re-declaration. Cancelling it also cancels a pending registration.
+      stopSettings = ctx.slots.inject('settings.section', () => {
+        const unregister = ctx.slots.register({
+          name: 'settings.section',
+          id: 'xmanrui-dsh-im',
+          order: 21,
+          label: () => t('IM机器人'),
+          locale: IM_LOCALE_NAMESPACE,
+          inject: () => panelDependencies,
+        }, buildPanelElement);
+        registered = true;
+        return () => {
+          registered = false;
+          unregister();
+        };
+      });
+    };
+
+    // Publish only after the default registration is established, so a
+    // consumer hiding it during service discovery cannot be overridden.
+    setSettingsVisible(true);
+    if (typeof ctx.provide === 'function') {
+      ctx.provide('dshImClient', Object.freeze({
+        version: 1,
+        render: (props) => disposed ? null : buildPanelElement(props),
+        setSettingsVisible,
+        settingsVisible: () => !disposed && registered,
+      }));
+    }
+    return () => {
+      disposed = true;
+      const stop = stopSettings;
+      stopSettings = null;
+      registered = false;
+      stop?.();
+    };
+  }, 'im-settings: client panel service');
 }

package/plugin-src/client/panel-error-boundary.js

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { h } from './i18n.js';
+
+/** Keep a broken IM subtree local when a shell renders it outside a slot. */
+export class IMPanelErrorBoundary extends React.Component {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  render() {
+    if (!this.state.failed) return this.props.children;
+    return h('section', { className: 'dim-page', role: 'alert' },
+      h('p', null, 'IM 面板加载失败'),
+      h('button', {
+        type: 'button',
+        onClick: () => this.setState({ failed: false }),
+      }, '重试'));
+  }
+}

package/plugin-src/host/channels/dingtalk/production.mjs

@@ -14,6 +14,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -58,7 +59,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -105,6 +106,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/feishu/production.mjs

@@ -26,6 +26,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -117,7 +118,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -201,6 +202,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     // This plugin is already hosted by a running DSH process. Starting a
     // second DSH would create a competing server and lifecycle.
     autostart: false,

package/plugin-src/host/channels/qq/production.mjs

@@ -14,6 +14,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -55,7 +56,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -96,6 +97,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/shared/production.mjs

@@ -16,6 +16,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import {
@@ -65,7 +66,7 @@ export async function createTokenProductionController(ctx, config, internals, de
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config, channel);
   const configStore = await new ResolvedConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -105,6 +106,7 @@ export async function createTokenProductionController(ctx, config, internals, de
   const harness = new ResolvedHarness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/slack/production.mjs

@@ -12,6 +12,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -44,7 +45,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config, 'slack');
   const configStore = await new ResolvedConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -84,6 +85,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new ResolvedHarness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/wecom/production.mjs

@@ -14,6 +14,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -55,7 +56,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -99,6 +100,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/wecom-app/production.mjs

@@ -14,6 +14,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -69,7 +70,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -133,6 +134,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/weixin/production.mjs

@@ -18,6 +18,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -90,7 +91,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const agentPresetCatalog = () => listAgentPresetCatalog(ctx);
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = diagnosticWorkspaces(internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load());
@@ -131,6 +132,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/plugin-src/host/channels/whatsapp/production.mjs

@@ -17,6 +17,7 @@ import {
   createWorkspaceAwareController,
   observeBotWorkspaceRemovals,
 } from '../../../../src/channels/shared/bot-workspace-store.mjs';
+import { prepareBotWorkspace } from '../../../../src/channels/shared/default-workspace.mjs';
 import { listAgentPresetCatalog } from '../../../../src/channels/shared/agent-preset.mjs';
 import { listModelCatalog } from '../../../../src/channels/shared/model-setting.mjs';
 import { createDeliveryAdapter } from '../../delivery-adapter.mjs';
@@ -65,7 +66,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const createSupervisor = internals.createConnectionSupervisor ?? createTokenConnectionSupervisor;
   const paths = pluginPaths(config);
   const configStore = await new ConfigStore(paths.config).load();
-  const defaultWorkspace = resolve(config.workspace ?? process.cwd());
+  const { defaultWorkspace, ungroupedWorkspace } = await prepareBotWorkspace(config);
   const WorkspaceStore = internals.WorkspaceStore ?? BotWorkspaceStore;
   const workspaces = internals.workspaces
     ?? await new WorkspaceStore(paths.workspaces, { defaultWorkspace }).load();
@@ -105,6 +106,7 @@ export async function createProductionController(ctx, config = {}, internals = {
   const harness = new Harness({
     ...connection,
     workspace: defaultWorkspace,
+    ungroupedWorkspace,
     autostart: false,
     dshBin: config.dshBin ?? 'dsh',
     ...(commandExecutor ? { commandExecutor } : {}),

package/src/channels/shared/bot-workspace-store.mjs

@@ -1,4 +1,5 @@
 import { validateBotAlias, withBotAlias } from './bot-alias.mjs';
+import { defaultImWorkspace, sameWorkspacePath } from './default-workspace.mjs';
 import {
   mkdir,
   readFile,
@@ -52,15 +53,6 @@ async function canonicalWorkspacePath(value) {
   return resolve(await realpath(value));
 }
 
-async function sameWorkspacePath(left, right) {
-  if (left === right) return true;
-  try {
-    return await canonicalWorkspacePath(left) === await canonicalWorkspacePath(right);
-  } catch {
-    return false;
-  }
-}
-
 function botIdOf(value) {
   if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
     throw new TypeError('Invalid bot id');
@@ -420,7 +412,7 @@ export class BotWorkspaceStore {
   #writeQueue = Promise.resolve();
   #botQueues = new Map();
 
-  constructor(path, { defaultWorkspace = process.cwd() } = {}) {
+  constructor(path, { defaultWorkspace = defaultImWorkspace() } = {}) {
     if (typeof path !== 'string' || !path) throw new TypeError('workspace store path is required');
     this.#path = path;
     this.#defaultWorkspace = resolve(defaultWorkspace);
@@ -1597,6 +1589,7 @@ export function createBotWorkspaceScope(
     if (!sessionId) return true;
     let sessionWorkspace = sessionGenerations.get(sessionId)?.workspace;
     let matches = false;
+    let unregistered = true;
     if (!sessionWorkspace && typeof harness.rpc === 'function') {
       // Read registration metadata only: adopting a Session is not a lookup.
       // Resolve by id before comparing real paths so symlink pins remain valid.
@@ -1609,7 +1602,11 @@ export function createBotWorkspaceScope(
       if (owners.length === 1 && typeof owners[0].path === 'string' && isAbsolute(owners[0].path)) {
         sessionWorkspace = owners[0].path;
       }
-    } else if (!sessionWorkspace && typeof harness.listWorkspaceSessions === 'function') {
+      unregistered = owners.length === 0;
+    }
+    if (!sessionWorkspace && unregistered && typeof harness.listWorkspaceSessions === 'function') {
+      // After a restart, default IM sessions have no registry owner. Reuse
+      // the read-only list, which also recognizes ungrouped default sessions.
       const listed = await harness.listWorkspaceSessions(await canonicalWorkspacePath(workspace));
       if (!Array.isArray(listed?.sessions)) {
         throw new TypeError('Harness returned an invalid workspace session list');

package/src/channels/shared/default-workspace.mjs

@@ -0,0 +1,28 @@
+import { mkdir, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+export function defaultImWorkspace(config = {}) {
+  const dshHome = config.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh');
+  return resolve(dshHome, 'im');
+}
+
+export async function sameWorkspacePath(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string'
+    || !isAbsolute(left) || !isAbsolute(right)) return false;
+  if (resolve(left) === resolve(right)) return true;
+  try {
+    return resolve(await realpath(left)) === resolve(await realpath(right));
+  } catch {
+    return false;
+  }
+}
+
+export async function prepareBotWorkspace(config = {}) {
+  const ungroupedWorkspace = defaultImWorkspace(config);
+  const defaultWorkspace = resolve(config.workspace ?? ungroupedWorkspace);
+  if (await sameWorkspacePath(defaultWorkspace, ungroupedWorkspace)) {
+    await mkdir(defaultWorkspace, { recursive: true });
+  }
+  return { defaultWorkspace, ungroupedWorkspace };
+}

package/src/channels/shared/harness-client.mjs

@@ -1,8 +1,10 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 
 import { adoptRegisteredWorkspaceSession } from './harness-session-binding.mjs';
+import { sameWorkspacePath } from './default-workspace.mjs';
 import {
   appendInboundFilesToPrompt,
   InboundFileError,
@@ -717,6 +719,7 @@ export class HarnessClient {
   #baseUrl;
   #apiProxy;
   #workspace;
+  #ungroupedWorkspace;
   #agentPreset;
   #autostart;
   #dshBin;
@@ -740,6 +743,7 @@ export class HarnessClient {
     apiProxy,
     interactionScope = apiProxy,
     workspace,
+    ungroupedWorkspace,
     agentPreset,
     autostart = false,
     dshBin = 'dsh',
@@ -788,6 +792,8 @@ export class HarnessClient {
       throw new TypeError('interactionScope must identify the current Host');
     }
     this.#workspace = workspace;
+    // Only the reserved IM directory bypasses grouping, even after /ws switches.
+    this.#ungroupedWorkspace = ungroupedWorkspace;
     // Keep an omitted preset absent so session.create resolves the Host's current default.
     this.#agentPreset = agentPreset ?? undefined;
     this.#autostart = Boolean(this.#baseUrl && autostart);
@@ -921,6 +927,38 @@ export class HarnessClient {
     await this.ensureRunning(options);
     const workspaceList = await this.rpc('workspace.list', {}, 30_000, options);
     const workspace = workspaceFromList(workspacePath, workspaceList);
+    if (await this.isUngroupedWorkspace(workspacePath)) {
+      const sessionList = await this.rpc('session.list', {}, 30_000, options);
+      if (!Array.isArray(sessionList?.items)) {
+        throw new Error('Harness returned an invalid response for session.list');
+      }
+      const registered = new Set();
+      const selected = new Set();
+      for (const item of workspaceList.items) {
+        if (!Array.isArray(item?.sessionIds)
+          || item.sessionIds.some((id) => typeof id !== 'string' || !id)) {
+          throw new Error('Harness returned invalid session IDs for workspace.list');
+        }
+        for (const id of item.sessionIds) registered.add(id);
+        if (await sameWorkspacePath(item.path, workspacePath)) {
+          for (const id of item.sessionIds) selected.add(id);
+        }
+      }
+      for (const item of sessionList.items) {
+        if (typeof item?.sessionId !== 'string' || !item.sessionId) {
+          throw new Error('Harness returned an invalid response for session.list');
+        }
+        // A matching cwd never overrides an explicit group assignment.
+        if (!registered.has(item.sessionId) && await this.isUngroupedWorkspace(item.cwd)) {
+          selected.add(item.sessionId);
+        }
+      }
+      return workspaceSessions(
+        { path: workspacePath, sessionIds: [...selected] },
+        workspaceList.archivedSessionIds,
+        sessionList,
+      );
+    }
     if (!workspace) return { workspace: workspacePath, sessions: [] };
     const sessionList = await this.rpc('session.list', {}, 30_000, options);
     return workspaceSessions(workspace, workspaceList.archivedSessionIds, sessionList);
@@ -988,6 +1026,10 @@ export class HarnessClient {
     return adoptRegisteredWorkspaceSession(this, value, options);
   }
 
+  async isUngroupedWorkspace(workspace) {
+    return sameWorkspacePath(workspace, this.#ungroupedWorkspace);
+  }
+
   async workspaceId(options = {}) {
     const { workspace = this.#workspace, ...rpcOptions } = options;
     const { items } = await this.rpc('workspace.list', {}, 30_000, rpcOptions);
@@ -999,9 +1041,13 @@ export class HarnessClient {
 
   async createSession(options = {}) {
     const { agentPreset: requestedPreset, ...rpcOptions } = options;
+    const workspace = rpcOptions.workspace ?? this.#workspace;
+    const ungrouped = await this.isUngroupedWorkspace(workspace);
+    if (ungrouped) await mkdir(workspace, { recursive: true });
     await this.ensureRunning(rpcOptions);
-    const workspaceId = await this.workspaceId(rpcOptions);
-    const payload = { workspaceId };
+    const payload = ungrouped
+      ? { cwd: workspace }
+      : { workspaceId: await this.workspaceId(rpcOptions) };
     const agentPreset = requestedPreset !== undefined ? requestedPreset : this.#agentPreset;
     if (agentPreset != null) payload.agentPreset = agentPreset;
     const created = await this.rpc('session.create', payload, 30_000, rpcOptions);

package/src/channels/shared/harness-session-binding.mjs

@@ -37,16 +37,13 @@ function sessionWorkspace(sessionId, value) {
     }
   }
 
-  if (owners.length === 0) {
-    throw bindingError('session-not-registered', 'The session is not registered to a Harness workspace');
-  }
-  if (owners.length !== 1) {
+  if (owners.length > 1) {
     throw bindingError(
       'session-workspace-ambiguous',
       'The session is registered to more than one Harness workspace',
     );
   }
-  if (UNSAFE_WORKSPACE_PATH.test(owners[0].path)) {
+  if (owners.length && UNSAFE_WORKSPACE_PATH.test(owners[0].path)) {
     throw new Error('Harness returned an unsafe workspace path for the session');
   }
   return {
@@ -82,20 +79,28 @@ function sessionSummary(sessionId, value) {
   if (title !== undefined && title !== null && typeof title !== 'string') {
     throw new Error('Harness returned an invalid session title for session.list');
   }
-  return { title: typeof title === 'string' ? title : null };
+  return { cwd: summary.cwd, title: typeof title === 'string' ? title : null };
 }
 
 export async function adoptRegisteredWorkspaceSession(client, value, options = {}, timeoutMs = 30_000) {
   const sessionId = validatedSessionId(value);
   await client.ensureRunning(options);
   const workspaceList = await client.rpc('workspace.list', {}, timeoutMs, options);
-  const { workspace, archived } = sessionWorkspace(sessionId, workspaceList);
+  let { workspace, archived } = sessionWorkspace(sessionId, workspaceList);
   const summary = sessionSummary(
     sessionId,
     await client.rpc('session.list', {}, timeoutMs, options),
   );
+  if (!workspace) {
+    if (typeof summary.cwd !== 'string' || !isAbsolute(summary.cwd)
+      || UNSAFE_WORKSPACE_PATH.test(summary.cwd)
+      || !await client.isUngroupedWorkspace?.(summary.cwd)) {
+      throw bindingError('session-not-registered', 'The session is not registered to a Harness workspace');
+    }
+    workspace = { path: summary.cwd };
+  }
   const adopted = await client.rpc('session.create', {
-    workspaceId: workspace.workspaceId,
+    ...(workspace.workspaceId ? { workspaceId: workspace.workspaceId } : { cwd: workspace.path }),
     sessionId,
   }, timeoutMs, options);
   if (!adopted || adopted.sessionId !== sessionId) {