@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.2

package/dist/builtin/intercom/broker/spawn.ts

@@ -1,11 +1,12 @@
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import net from "net";
-import { isBunBinary } from "@bastani/atomic";
+import { createChildProcessEnvironment, isBunBinary } from "@bastani/atomic";
 import {
+  getBrokerLogPath,
   getBrokerPidPath,
   getBrokerSocketPath,
   getBrokerSpawnLockPath,
@@ -17,6 +18,22 @@ const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 const BROKER_SOCKET = getBrokerSocketPath();
 const BROKER_PID = getBrokerPidPath();
 const BROKER_SPAWN_LOCK = getBrokerSpawnLockPath();
+const BROKER_LOG = getBrokerLogPath();
+
+/**
+ * How much of the broker startup log is read back into an error message.
+ *
+ * This is a read bound only. The file's physical size is capped separately, inside the broker
+ * process, by {@link BROKER_LOG_MAX_BYTES} in `bounded-stderr.ts` — nothing the parent does can
+ * bound a detached child that keeps appending after the parent exits.
+ */
+export const BROKER_LOG_TAIL_BYTES = 8 * 1024;
+
+/** First readiness poll interval; doubles up to {@link BROKER_POLL_MAX_INTERVAL_MS}. */
+export const BROKER_POLL_INITIAL_INTERVAL_MS = 10;
+
+/** Upper bound for the readiness poll interval, matching the historic flat poll. */
+export const BROKER_POLL_MAX_INTERVAL_MS = 100;
 
 type BrokerRuntime = "node" | "bun-source" | "bun-binary";
 
@@ -49,20 +66,6 @@ function requireFromExtensionDir(extensionDir: string): NodeJS.Require {
   return createRequire(join(extensionDir, "package.json"));
 }
 
-function resolveTsxCliPath(extensionDir: string): string | null {
-  try {
-    const tsxMain = requireFromExtensionDir(extensionDir).resolve("tsx");
-    return join(dirname(tsxMain), "cli.mjs");
-  } catch {
-    const bundledTsx = join(extensionDir, "node_modules", "tsx", "dist", "cli.mjs");
-    return existsSync(bundledTsx) ? bundledTsx : null;
-  }
-}
-
-export function getTsxCliPath(extensionDir: string = EXTENSION_DIR): string {
-  return resolveTsxCliPath(extensionDir) ?? join(extensionDir, "node_modules", "tsx", "dist", "cli.mjs");
-}
-
 export function getJitiCliPath(extensionDir: string = EXTENSION_DIR): string {
   try {
     const jitiPackage = requireFromExtensionDir(extensionDir).resolve("jiti/package.json");
@@ -72,8 +75,13 @@ export function getJitiCliPath(extensionDir: string = EXTENSION_DIR): string {
   }
 }
 
+/**
+ * jiti is a dependency-free pure-JS TypeScript loader, so the Node broker path no longer needs
+ * tsx and its platform-specific esbuild binary. The `npx --no-install tsx` config pair remains
+ * a recognized compatibility sentinel; nothing resolves the tsx package.
+ */
 function getDefaultBrokerRunnerPath(extensionDir: string): string {
-  return resolveTsxCliPath(extensionDir) ?? getJitiCliPath(extensionDir);
+  return getJitiCliPath(extensionDir);
 }
 
 function getDefaultBrokerCommandParts(
@@ -122,6 +130,25 @@ export function getWindowsBrokerCommandLine(
   return [quoteWindowsArg(brokerCommand), ...brokerArgs.map(quoteWindowsArg), quoteWindowsArg(brokerPath)].join(" ");
 }
 
+/**
+ * `WshShell.Run` does not hand the launched process the parent's standard handles, so a file
+ * descriptor passed to `wscript.exe` would only ever capture the launcher. Run the broker under
+ * `cmd.exe /s /c` instead and append its stderr to the same log the direct path writes.
+ * `/s` makes cmd strip exactly the outer quote pair and use the remainder verbatim.
+ *
+ * Returns the command line unchanged when it contains a `%`. cmd expands `%NAME%` at parse time
+ * and there is no reliable way to escape a literal percent on a `cmd /c` command line — `^` does
+ * not cover it, and `%%` is a batch-file escape rather than a command-line one. Wrapping such a
+ * command would hand the broker different arguments than the user configured, so the redirect is
+ * dropped instead: launching correctly without a captured log beats launching wrongly with one.
+ * A `%` reaches here only from a custom `brokerCommand`/`brokerArgs` or an install path that
+ * contains one, and the direct (non-launcher) Windows path still captures stderr normally.
+ */
+export function getWindowsStderrRedirectCommandLine(commandLine: string, logPath: string): string {
+  if (commandLine.includes("%")) return commandLine;
+  return `cmd.exe /s /c "${commandLine} 2>>${quoteWindowsArg(logPath)}"`;
+}
+
 export function getWindowsHiddenLauncherScript(commandLine: string): string {
   return [
     'Set WshShell = CreateObject("WScript.Shell")',
@@ -149,6 +176,7 @@ export function getBrokerLaunchSpec(
   intercomDir: string = INTERCOM_DIR,
   nodePath: string = process.execPath,
   runtime: BrokerRuntime = getCurrentBrokerRuntime(),
+  logPath: string = BROKER_LOG,
 ): BrokerLaunchSpec {
   if (platform === "win32") {
     const launcherPath = getWindowsHiddenLauncherPath(intercomDir);
@@ -157,7 +185,10 @@ export function getBrokerLaunchSpec(
       command: "wscript.exe",
       args: [launcherPath],
       launcherPath,
-      launcherCommandLine: getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath, brokerCommand, brokerArgs, runtime),
+      launcherCommandLine: getWindowsStderrRedirectCommandLine(
+        getWindowsBrokerCommandLine(brokerPath, extensionDir, nodePath, brokerCommand, brokerArgs, runtime),
+        logPath,
+      ),
     };
   }
 
@@ -177,22 +208,68 @@ export function getBrokerLaunchSpec(
   };
 }
 
-export function getBrokerSpawnOptions(extensionDir: string = EXTENSION_DIR): {
+/**
+ * The broker is detached and outlives this process, so its stderr goes to an already-open file
+ * descriptor rather than a pipe: a long-lived pipe would keep the parent's event loop attached
+ * and break once the parent exits.
+ */
+export function getBrokerSpawnOptions(
+  extensionDir: string = EXTENSION_DIR,
+  stderr: number | "ignore" = "ignore",
+): {
   detached: true;
-  stdio: "ignore";
+  stdio: ["ignore", "ignore", number | "ignore"];
   cwd: string;
   env: NodeJS.ProcessEnv;
   windowsHide: true;
 } {
   return {
     detached: true,
-    stdio: "ignore",
+    stdio: ["ignore", "ignore", stderr],
     cwd: extensionDir,
-    env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    env: createChildProcessEnvironment({ NODE_NO_WARNINGS: "1" }),
     windowsHide: true,
   };
 }
 
+/** Truncate (or create) the broker log so each spawn starts from a bounded, current file. */
+function resetBrokerLog(logPath: string = BROKER_LOG): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  closeSync(openSync(logPath, "w"));
+}
+
+/** Read at most {@link BROKER_LOG_TAIL_BYTES} trailing bytes of the broker log. */
+export function readBrokerLogTail(logPath: string = BROKER_LOG, maxBytes: number = BROKER_LOG_TAIL_BYTES): string {
+  let fd: number | undefined;
+  try {
+    fd = openSync(logPath, "r");
+    const size = statSync(logPath).size;
+    const length = Math.min(size, maxBytes);
+    if (length <= 0) return "";
+    const buffer = Buffer.allocUnsafe(length);
+    const read = readSync(fd, buffer, 0, length, size - length);
+    return buffer.subarray(0, read).toString("utf-8").trim();
+  } catch {
+    // A missing or unreadable log simply yields no diagnostic tail.
+    return "";
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // Already closed.
+      }
+    }
+  }
+}
+
+/** Path plus bounded stderr tail, appended to every broker startup failure. */
+export function describeBrokerLog(logPath: string = BROKER_LOG): string {
+  const tail = readBrokerLogTail(logPath);
+  if (tail.length === 0) return `Broker log: ${logPath} (empty)`;
+  return `Broker log: ${logPath}\n--- broker stderr (last ${Buffer.byteLength(tail)} bytes) ---\n${tail}`;
+}
+
 function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error));
 }
@@ -220,7 +297,18 @@ export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: str
     if (launch.kind === "windows-launcher") {
       writeWindowsHiddenLauncher(launch.launcherCommandLine, launch.launcherPath);
     }
-    const child = spawn(launch.command, launch.args, getBrokerSpawnOptions());
+    // Reset before spawning either way: the Windows launcher appends to this same path.
+    resetBrokerLog();
+    // The Windows launcher redirects the broker's own stderr, so only the direct spawn
+    // needs the descriptor. Node duplicates it during spawn, so the parent copy is closed
+    // immediately afterwards rather than being held open for the broker's lifetime.
+    const logFd = launch.kind === "direct" ? openSync(BROKER_LOG, "a") : undefined;
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(launch.command, launch.args, getBrokerSpawnOptions(EXTENSION_DIR, logFd ?? "ignore"));
+    } finally {
+      if (logFd !== undefined) closeSync(logFd);
+    }
     child.unref();
 
     await new Promise<void>((resolve, reject) => {
@@ -231,7 +319,9 @@ export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: str
 
       const onError = (error: Error) => {
         cleanup();
-        reject(new Error(`Failed to spawn intercom broker: ${error.message}`, { cause: error }));
+        reject(
+          new Error(`Failed to spawn intercom broker: ${error.message}\n${describeBrokerLog()}`, { cause: error }),
+        );
       };
 
       const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
@@ -240,10 +330,12 @@ export async function spawnBrokerIfNeeded(brokerCommand: string, brokerArgs: str
         }
         cleanup();
         if (signal) {
-          reject(new Error(`Intercom broker exited before startup with signal ${signal}`));
+          reject(new Error(`Intercom broker exited before startup with signal ${signal}\n${describeBrokerLog()}`));
           return;
         }
-        reject(new Error(`Intercom broker exited before startup with code ${code ?? "unknown"}`));
+        reject(
+          new Error(`Intercom broker exited before startup with code ${code ?? "unknown"}\n${describeBrokerLog()}`),
+        );
       };
 
       child.once("error", onError);
@@ -364,13 +456,20 @@ function releaseSpawnLock(): void {
   }
 }
 
-async function waitForBroker(timeoutMs = 5000): Promise<void> {
+/**
+ * Poll the broker socket with a short initial interval and bounded exponential backoff.
+ * Startup is tens of milliseconds, so the previous flat 100 ms sleep dominated it; the
+ * overall timeout semantics are unchanged.
+ */
+export async function waitForBroker(timeoutMs = 5000): Promise<void> {
   const start = Date.now();
+  let interval = BROKER_POLL_INITIAL_INTERVAL_MS;
   while (Date.now() - start < timeoutMs) {
     if (await checkSocketConnectable()) {
       return;
     }
-    await sleep(100);
+    await sleep(interval);
+    interval = Math.min(interval * 2, BROKER_POLL_MAX_INTERVAL_MS);
   }
-  throw new Error("Broker failed to start within timeout");
+  throw new Error(`Broker failed to start within timeout\n${describeBrokerLog()}`);
 }

package/dist/builtin/intercom/foreground-detach-handoff.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@bastani/atomic";
+import { isStaleExtensionContextError, type ExtensionAPI } from "@bastani/atomic";
 import type { Message, SessionInfo } from "./types.js";
 
 export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
@@ -97,29 +97,45 @@ export class ForegroundDetachHandoff {
         if (settled) return;
         settled = true;
         if (timeout) clearTimeout(timeout);
-        unsubscribe?.();
+        try {
+          unsubscribe?.();
+        } catch (error) {
+          if (!isStaleExtensionContextError(error)) throw error;
+          // Stale event-bus cleanup must not change the handshake result.
+        }
         signal.removeEventListener("abort", cancel);
         resolve(disposition);
       };
       const cancel = () => finish("cancelled");
-      unsubscribe = this.pi.events?.on(INTERCOM_DETACH_RESPONSE_EVENT, (payload) => {
-        if (!payload || typeof payload !== "object") return;
-        const response = payload as Partial<DetachHandshake> & { accepted?: unknown };
-        if (response.accepted === true
-          && response.phase === route.phase
-          && response.requestId === route.requestId
-          && response.messageId === route.messageId
-          && response.childIntercomTarget === route.childIntercomTarget
-          && response.senderId === route.senderId
-          && response.runtimeGeneration === route.runtimeGeneration) finish("acknowledged");
-      });
+      try {
+        unsubscribe = this.pi.events?.on(INTERCOM_DETACH_RESPONSE_EVENT, (payload) => {
+          if (!payload || typeof payload !== "object") return;
+          const response = payload as Partial<DetachHandshake> & { accepted?: unknown };
+          if (response.accepted === true
+            && response.phase === route.phase
+            && response.requestId === route.requestId
+            && response.messageId === route.messageId
+            && response.childIntercomTarget === route.childIntercomTarget
+            && response.senderId === route.senderId
+            && response.runtimeGeneration === route.runtimeGeneration) finish("acknowledged");
+        });
+      } catch (error) {
+        if (!isStaleExtensionContextError(error)) throw error;
+        finish("timed-out");
+        return;
+      }
       signal.addEventListener("abort", cancel, { once: true });
       timeout = setTimeout(() => finish("timed-out"), this.ackTimeoutMs);
       if (signal.aborted) {
         cancel();
         return;
       }
-      this.pi.events?.emit(INTERCOM_DETACH_REQUEST_EVENT, route);
+      try {
+        this.pi.events?.emit(INTERCOM_DETACH_REQUEST_EVENT, route);
+      } catch (error) {
+        if (!isStaleExtensionContextError(error)) throw error;
+        finish("timed-out");
+      }
     });
   }
 

package/dist/builtin/intercom/group.ts

@@ -1,46 +1,85 @@
-import { getEnvValue } from "@bastani/atomic";
+/**
+ * Group primitives shared by the detached broker and the host extension.
+ * Keep this module free of host-package imports: the broker loads it in a
+ * detached process with only Node built-ins and Intercom-local modules.
+ */
+
+/**
+ * Mirrors `getEnvValue("ATOMIC_INTERCOM_GROUP")` locally so the detached broker subprocess
+ * needs no host package. `getEnvValue` returns the first value that is `!== undefined` across
+ * `[ATOMIC_INTERCOM_GROUP, PI_INTERCOM_GROUP]`, so a defined-but-empty ATOMIC value
+ * deliberately shadows the legacy name and yields `""`; `resolveHomeGroup` then falls through
+ * on the empty string. `??` reproduces that exactly — do not "improve" it to `||`.
+ */
+function intercomGroupFromEnv(): string | undefined {
+	return process.env.ATOMIC_INTERCOM_GROUP ?? process.env.PI_INTERCOM_GROUP;
+}
 
 /** The implicit group every ungrouped session belongs to. */
 export const DEFAULT_GROUP = "default";
 
+const RESERVED_RUNTIME_GROUPS = new Set(["true", "auto"]);
+
 /**
  * Normalize an intercom group id. Undefined, empty, or whitespace-only values
  * collapse to the shared {@link DEFAULT_GROUP} so ungrouped sessions all compare
  * equal and can still talk to each other (backward compatible).
  */
 export function normalizeGroup(value?: string | null): string {
-  if (typeof value !== "string") return DEFAULT_GROUP;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : DEFAULT_GROUP;
+	if (typeof value !== "string") return DEFAULT_GROUP;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : DEFAULT_GROUP;
 }
 
-/** `getEnvValue("ATOMIC_INTERCOM_GROUP")` also resolves the legacy `PI_INTERCOM_GROUP`. */
-const INTERCOM_GROUP_ENV = "ATOMIC_INTERCOM_GROUP";
+/**
+ * Validate a group requested by the runtime join action. `default` is a real,
+ * explicit group name; `true` and `auto` remain reserved for subagent auto-grouping.
+ */
+export function validateRuntimeGroup(value: unknown): string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error("A non-empty intercom group name is required");
+	}
+	const group = normalizeGroup(value);
+	if (RESERVED_RUNTIME_GROUPS.has(group.toLowerCase())) {
+		throw new Error(`Intercom group name "${group}" is reserved; choose another name`);
+	}
+	return group;
+}
 
 interface HomeGroupContext {
-  orchestrationContext?: { intercomGroup?: string } | undefined;
+	orchestrationContext?: { intercomGroup?: string } | undefined;
+	subagentPolicy?: { intercomGroup?: string } | undefined;
+	/** Accepted from the live extension context but intentionally ignored for home resolution. */
+	sessionManager?: { getSessionId(): string } | undefined;
 }
 
 /**
- * Resolve a session's home intercom group with precedence (most specific first):
- * per-session orchestrationContext.intercomGroup (in-process workflow stages) >
- * env ATOMIC_INTERCOM_GROUP (also PI_INTERCOM_GROUP legacy) > config.json "group" >
- * "default". Always returns a concrete normalized string.
+ * Resolve a session's static home intercom group with precedence (most specific first):
+ * admitted subagentPolicy.intercomGroup > orchestrationContext.intercomGroup >
+ * env ATOMIC_INTERCOM_GROUP (also PI_INTERCOM_GROUP legacy) > config.json "group" > "default".
+ * Always returns a concrete normalized string.
+ *
+ * Runtime join entries are deliberately not read here. They are child-inheritance state, not
+ * home state, so a reconnect cannot turn the joined group into the destination of `leave`.
  */
 export function resolveHomeGroup(
-  config: { group?: string } | undefined,
-  ctx?: HomeGroupContext | null,
+	config: { group?: string } | undefined,
+	ctx?: HomeGroupContext | null,
 ): string {
-  const fromContext = ctx?.orchestrationContext?.intercomGroup;
-  if (typeof fromContext === "string" && fromContext.trim().length > 0) {
-    return normalizeGroup(fromContext);
-  }
-  const fromEnv = getEnvValue(INTERCOM_GROUP_ENV);
-  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
-    return normalizeGroup(fromEnv);
-  }
-  if (config && typeof config.group === "string" && config.group.trim().length > 0) {
-    return normalizeGroup(config.group);
-  }
-  return DEFAULT_GROUP;
+	const fromPolicy = ctx?.subagentPolicy?.intercomGroup;
+	if (typeof fromPolicy === "string" && fromPolicy.trim().length > 0) {
+		return normalizeGroup(fromPolicy);
+	}
+	const fromContext = ctx?.orchestrationContext?.intercomGroup;
+	if (typeof fromContext === "string" && fromContext.trim().length > 0) {
+		return normalizeGroup(fromContext);
+	}
+	const fromEnv = intercomGroupFromEnv();
+	if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+		return normalizeGroup(fromEnv);
+	}
+	if (config && typeof config.group === "string" && config.group.trim().length > 0) {
+		return normalizeGroup(config.group);
+	}
+	return DEFAULT_GROUP;
 }

package/dist/builtin/intercom/index-heavy.ts

@@ -29,6 +29,7 @@ import { bindWorkflowReplyTracker, preserveWorkflowReplyTracker } from "./workfl
 import { routeClosedWorkflowStageMessage } from "./closed-workflow-stage-message.js";
 import { createWorkflowStageDeliveryFailureHandler } from "./workflow-stage-delivery-failure.js";
 import { resolveHomeGroup } from "./group.js";
+import { clearRuntimeIntercomGroup, setRuntimeIntercomGroup } from "./runtime-group.js";
 import { reconnectDelayMs } from "./reconnect-backoff.js";
 import { SupervisorAuthorizationRegistry } from "./supervisor-authorization-registry.js";
 if (process.env.ATOMIC_TEST_LAZY_IMPORT_SENTINEL === "1") {
@@ -66,6 +67,8 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
   let runtimeStarted = false;
   let runtimeGeneration = 0;
   let agentRunning = false;
+  let sessionHomeGroup: string | null = null;
+  let joinedGroup: string | null = null;
   const activeTools = new Map<string, string>();
   let replyTracker = new ReplyTracker();
   const replyWaiters = new ReplyWaiterSlot();
@@ -108,6 +111,23 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
     const lifecycleStatus = activeToolName ? `tool:${activeToolName}` : agentRunning ? "thinking" : "idle";
     return config.status ? `${lifecycleStatus} · ${config.status}` : lifecycleStatus;
   }
+  function resolveSessionHomeGroup(): string {
+    return sessionHomeGroup ?? resolveHomeGroup(config, getLiveContext());
+  }
+  function currentIntercomGroup(): string {
+    return joinedGroup ?? resolveSessionHomeGroup();
+  }
+  function setJoinedGroup(group: string): void {
+    const sessionId = currentSessionId;
+    if (!sessionId) return;
+    setRuntimeIntercomGroup(sessionId, group);
+    joinedGroup = group;
+  }
+  function clearJoinedGroup(): void {
+    const sessionId = currentSessionId;
+    joinedGroup = null;
+    if (sessionId) clearRuntimeIntercomGroup(sessionId);
+  }
   function buildRegistration(): Omit<SessionInfo, "id"> {
     const liveContext = getLiveContext();
     if (!liveContext || !currentSessionId || sessionStartedAt === null) {
@@ -122,7 +142,7 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
       startedAt: sessionStartedAt,
       lastActivity: Date.now(),
       status: currentStatus(),
-      group: resolveHomeGroup(config, getLiveContext()),
+      group: currentIntercomGroup(),
     };
   }
   function syncPresenceIdentity(sessionId: string): void {
@@ -150,7 +170,7 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
     return Boolean(resolvedTo && activeClient?.sessionId && resolvedTo === activeClient.sessionId)
       || targets.has(to.trim().toLowerCase());
   }
-  registerLateStageMessageRouter(pi, inboundDeliveries, () => replyTracker, () => resolveHomeGroup(config, getLiveContext()));
+  registerLateStageMessageRouter(pi, inboundDeliveries, () => replyTracker, currentIntercomGroup);
   const sendIncomingMessage = createIncomingMessageSender({
     pi,
     currentGeneration: () => runtimeGeneration,
@@ -408,7 +428,9 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
           throw new Error("Intercom runtime no longer active");
         }
         client = nextClient;
-        if (nextClient.sessionId) process.env[INTERCOM_SESSION_ID_ENV] = nextClient.sessionId;
+        if (nextClient.sessionId) {
+          process.env[INTERCOM_SESSION_ID_ENV] = nextClient.sessionId;
+        }
         reconnectAttempt = 0;
         return nextClient;
       } catch (error) {
@@ -440,7 +462,7 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
     ensureConnected,
     authorizeSupervisorChild: (childName) => supervisorAuthorizations.authorize(childName, () => ensureConnected("background")),
     resolveSessionTarget: resolveSessionTargetId,
-    homeGroup: () => resolveHomeGroup(config, getLiveContext()),
+    homeGroup: currentIntercomGroup,
   });
 
   registerIntercomLifecycle(pi, {
@@ -453,7 +475,15 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
     incrementRuntimeGeneration: () => { runtimeGeneration += 1; foregroundDetachHandoff.reset(); return runtimeGeneration; },
     resetReconnectAttempt: () => { reconnectAttempt = 0; },
     clearReconnectTimer,
-    setRuntimeContext: (value) => { runtimeContext = value; },
+    setRuntimeContext: (value) => {
+      if (value === null) {
+        clearJoinedGroup();
+        sessionHomeGroup = null;
+      } else {
+        sessionHomeGroup = resolveHomeGroup(config, value);
+      }
+      runtimeContext = value;
+    },
     setCurrentSessionId: (value) => { currentSessionId = value; },
     setCurrentModel: (value) => { currentModel = value; },
     setSessionStartedAt: (value) => { sessionStartedAt = value; },
@@ -492,6 +522,9 @@ export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: Int
     syncPresenceIdentity,
     beginReplyWait: (from, replyTo, signal) => replyWaiters.begin(from, replyTo, signal),
     confirmSend: config.confirmSend,
+    homeGroup: resolveSessionHomeGroup,
+    setJoinedGroup,
+    clearJoinedGroup,
     replyTracker: () => replyTracker,
     hasReplyWaiter: () => replyWaiters.has(),
   });

package/dist/builtin/intercom/index.ts

@@ -412,14 +412,18 @@ Sessions belong to an intercom group and can ONLY message sessions in the same g
 Usage:
   intercom({ action: "list" })                    → List sessions in your group
   intercom({ action: "list", group: "name" })     → Read-only peek at another group's sessions
+  intercom({ action: "join", group: "name" })     → Join or create a named group
+  intercom({ action: "leave" })                   → Return to your resolved home group
   intercom({ action: "send", to: "session-name", message: "..." })  → Send message (own group only)
   intercom({ action: "ask", to: "session-name", message: "..." })   → Ask and wait for reply
   intercom({ action: "reply", message: "..." })                      → Reply to the active/single pending ask
   intercom({ action: "pending" })                                      → List unresolved inbound asks
-  intercom({ action: "status" })                  → Show connection status and your group`,
+  intercom({ action: "status" })                  → Show connection status and your group
+
+"default" is the shared group; "true" and "auto" are reserved for subagent auto-groups. Joining does not grant cross-group access; contact_supervisor remains the only cross-group path.`,
 		promptSnippet: "Use to coordinate with other local agent sessions in your intercom group: list peers, send updates, ask for help, or check intercom connectivity. Groups are isolated; you can only message sessions in your own group.",
 		parameters: Type.Object({
-			action: Type.String({ description: "Action: 'list', 'send', 'ask', 'reply', 'pending', or 'status'" }),
+			action: Type.String({ description: "Action: 'list', 'join', 'leave', 'send', 'ask', 'reply', 'pending', or 'status'" }),
 			to: Type.Optional(Type.String({ description: "Target session name or ID (for 'send', 'ask', or disambiguating 'reply')" })),
 			message: Type.Optional(Type.String({ description: "Message to send (for 'send', 'ask', or 'reply' action)" })),
 			attachments: Type.Optional(Type.Array(Type.Object({
@@ -429,7 +433,7 @@ Usage:
 				language: Type.Optional(Type.String()),
 			}))),
 			replyTo: Type.Optional(Type.String({ description: "Message ID to reply to (for threading or responding to an 'ask')" })),
-			group: Type.Optional(Type.String({ description: "Read-only group filter for 'list'/'status'; 'send'/'ask' are locked to your own group." })),
+			group: Type.Optional(Type.String({ description: "Group name for 'join'; read-only group filter for 'list'/'status'. 'send'/'ask' are locked to your own group." })),
 		}),
 		execute: (...args) => executeHeavyTool(loadHeavy, "intercom", args),
 		renderResult: (...args) => renderHeavyToolResult(loadedHeavy?.heavy ?? null, "intercom", args),