@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.8

package/dist/builtin/intercom/broker/client-message-validation.ts

@@ -8,6 +8,14 @@ function isAttachment(value: unknown): value is Attachment {
   return attachment.language === undefined || typeof attachment.language === "string";
 }
 
+function isMessageSource(value: unknown): value is NonNullable<Message["source"]> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const source = value as Record<string, unknown>;
+  return typeof source.subagentRunId === "string"
+    && (source.subagentAgent === undefined || typeof source.subagentAgent === "string")
+    && (source.subagentIndex === undefined || typeof source.subagentIndex === "number");
+}
+
 export function isMessage(value: unknown): value is Message {
   if (typeof value !== "object" || value === null) return false;
   const message = value as Record<string, unknown>;
@@ -15,6 +23,7 @@ export function isMessage(value: unknown): value is Message {
   if (message.replyTo !== undefined && typeof message.replyTo !== "string") return false;
   if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") return false;
   if (message.replyError !== undefined && typeof message.replyError !== "string") return false;
+  if (message.source !== undefined && !isMessageSource(message.source)) return false;
   if (typeof message.content !== "object" || message.content === null) return false;
   const content = message.content as Record<string, unknown>;
   if (typeof content.text !== "string") return false;

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

@@ -24,8 +24,36 @@ export interface SendOptions {
 export interface SendResult {
   id: string;
   delivered: boolean;
+  queued?: boolean;
   reason?: string;
+	reasonCode?: "message_id_conflict";
+  runId?: string;
+  stageKey?: string;
+  position?: number;
 }
+
+export interface PendingStageMessageRequest {
+	readonly requestId: string;
+	readonly from: SessionInfo;
+	readonly runId: string;
+	readonly stageKey: string;
+	readonly message: Message;
+	readonly senderRegistrationName?: string;
+	readonly senderReturnAddress?: string;
+	readonly live?: boolean;
+}
+
+export interface PendingStageNotificationRequest {
+	readonly requestId: string;
+	readonly from: SessionInfo;
+	readonly message: Message;
+}
+
+export type PendingStageMessageResult =
+	| { readonly outcome: "queued"; readonly position: number }
+	| { readonly outcome: "delivered" }
+	| { readonly outcome: "forward" }
+	| { readonly outcome: "refused"; readonly reason: string; readonly reasonCode?: "message_id_conflict" };
 export interface PresenceUpdates {
   name?: string;
   status?: string;
@@ -44,6 +72,7 @@ function toError(error: unknown): Error {
 
 
 export class IntercomClient extends EventEmitter {
+	private readonly returnAddress: string;
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
   private _supervisorSessionId: string | null = null;
@@ -52,6 +81,7 @@ export class IntercomClient extends EventEmitter {
   private pendingSends = new PendingSendRegistry();
   private pendingLists = new Map<string, { resolve: (sessions: SessionInfo[]) => void; reject: (e: Error) => void }>();
   private pendingPresence = new Map<string, { resolve: (group: string) => void; reject: (error: Error) => void }>();
+  private pendingLiveWorkflowStageRoutes = new Map<string, { resolve(): void; reject(error: Error): void }>();
 
   private pendingSupervisorAuthorizations = new Map<string, {
     resolve: (authorization: SupervisorAuthorization) => void;
@@ -60,14 +90,22 @@ export class IntercomClient extends EventEmitter {
   private disconnecting = false;
   private disconnectError: Error | null = null;
 
+	constructor(returnAddress: string = randomUUID()) {
+		super();
+		if (returnAddress.length === 0) throw new Error("Intercom return address must not be empty");
+		this.returnAddress = returnAddress;
+	}
+
   private failPending(error: Error): void {
     this.pendingSends.rejectAll(error);
     for (const pending of this.pendingLists.values()) pending.reject(error);
     for (const pending of this.pendingSupervisorAuthorizations.values()) pending.reject(error);
     for (const pending of this.pendingPresence.values()) pending.reject(error);
+    for (const pending of this.pendingLiveWorkflowStageRoutes.values()) pending.reject(error);
     this.pendingLists.clear();
     this.pendingSupervisorAuthorizations.clear();
     this.pendingPresence.clear();
+    this.pendingLiveWorkflowStageRoutes.clear();
   }
 
 
@@ -220,6 +258,7 @@ export class IntercomClient extends EventEmitter {
         writeMessage(socket, {
           type: "register",
           session,
+			returnAddress: this.returnAddress,
           ...(supervisor ? { supervisor } : {}),
           ...(supervisorOwnerToken ? { supervisorOwnerToken } : {}),
         });
@@ -303,6 +342,70 @@ export class IntercomClient extends EventEmitter {
         }
         this.emit("message", from, message, channel);
         break;
+      }
+		case "pending_stage_message": {
+			const { requestId, from, senderRegistrationName, senderReturnAddress, runId, stageKey, message, live } = brokerMessage;
+			if (
+				typeof requestId !== "string" ||
+				!isSessionInfo(from) ||
+				(senderRegistrationName !== undefined && typeof senderRegistrationName !== "string") ||
+				(senderReturnAddress !== undefined && typeof senderReturnAddress !== "string") ||
+				typeof runId !== "string" ||
+				typeof stageKey !== "string" ||
+				!isMessage(message) ||
+				(live !== undefined && typeof live !== "boolean")
+			) {
+				throw new Error("Invalid pending-stage message event");
+			}
+			this.emit("pending_stage_message", {
+				requestId,
+				from,
+				...(senderRegistrationName === undefined ? {} : { senderRegistrationName }),
+				...(senderReturnAddress === undefined ? {} : { senderReturnAddress }),
+				runId,
+				stageKey,
+				message,
+				...(live === true ? { live: true } : {}),
+			} satisfies PendingStageMessageRequest);
+			break;
+		}
+		case "pending_stage_notification": {
+			const { requestId, from, message } = brokerMessage;
+			if (typeof requestId !== "string" || !isSessionInfo(from) || !isMessage(message)) {
+				throw new Error("Invalid pending-stage notification event");
+			}
+			this.emit("pending_stage_notification", {
+				requestId,
+				from,
+				message,
+			} satisfies PendingStageNotificationRequest);
+			break;
+		}
+      case "live_workflow_stage_route_registered": {
+        const { requestId } = brokerMessage;
+        if (typeof requestId !== "string") throw new Error("Invalid live workflow-stage route registration");
+        const pending = this.pendingLiveWorkflowStageRoutes.get(requestId);
+        if (!pending) return;
+        this.pendingLiveWorkflowStageRoutes.delete(requestId);
+        pending.resolve();
+        break;
+      }
+      case "queued": {
+        const { messageId, attemptId, runId, stageKey, position } = brokerMessage;
+        if (
+          typeof messageId !== "string" ||
+          (attemptId !== undefined && typeof attemptId !== "string") ||
+          typeof runId !== "string" ||
+          typeof stageKey !== "string" ||
+          typeof position !== "number" ||
+          position < 1
+        ) {
+          throw new Error("Invalid queued message");
+        }
+        const result = { id: messageId, delivered: false, queued: true, runId, stageKey, position } as const;
+        if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
+        else this.pendingSends.resolve(messageId, attemptId, result);
+        break;
       }
       case "delivered": {
         const { messageId, attemptId } = brokerMessage;
@@ -315,14 +418,24 @@ export class IntercomClient extends EventEmitter {
         break;
       }
       case "delivery_failed": {
-        const { messageId, attemptId, reason } = brokerMessage;
-        if (typeof messageId !== "string" || (attemptId !== undefined && typeof attemptId !== "string") || typeof reason !== "string") {
-          throw new Error("Invalid delivery_failed message");
-        }
-        const result = { id: messageId, delivered: false, reason } as const;
-        if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
-        else this.pendingSends.resolve(messageId, attemptId, result);
-        break;
+		const { messageId, attemptId, reason, reasonCode } = brokerMessage;
+		if (
+			typeof messageId !== "string" ||
+			(attemptId !== undefined && typeof attemptId !== "string") ||
+			typeof reason !== "string" ||
+			(reasonCode !== undefined && reasonCode !== "message_id_conflict")
+		) {
+			throw new Error("Invalid delivery_failed message");
+		}
+		const result = {
+			id: messageId,
+			delivered: false,
+			reason,
+			...(reasonCode === undefined ? {} : { reasonCode }),
+		} as const;
+		if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
+		else this.pendingSends.resolve(messageId, attemptId, result);
+		break;
       }
       case "session_joined": {
         if (!isSessionInfo(brokerMessage.session)) {
@@ -490,15 +603,92 @@ export class IntercomClient extends EventEmitter {
       }
     });
   }
+  registerPendingStageRoute(runId: string, group: string, capability: string): void {
+    writeMessage(this.requireActiveSocket(), { type: "register_pending_stage_route", runId, group, capability });
+  }
+
+  registerLiveWorkflowStageRoute(runId: string, stageKeys: readonly string[], capability: string): Promise<void> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      this.pendingLiveWorkflowStageRoutes.set(requestId, { resolve, reject });
+      try {
+        writeMessage(socket, {
+          type: "register_live_workflow_stage_route",
+          requestId,
+          runId,
+          stageKeys: [...stageKeys],
+          capability,
+        });
+      } catch (error) {
+        this.pendingLiveWorkflowStageRoutes.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
+
+	respondPendingStageMessage(requestId: string, result: PendingStageMessageResult): void {
+		const socket = this.requireActiveSocket();
+		writeMessage(
+			socket,
+			result.outcome === "queued"
+				? { type: "pending_stage_message_result", requestId, outcome: "queued", position: result.position }
+				: result.outcome === "refused"
+					? {
+							type: "pending_stage_message_result",
+							requestId,
+							outcome: "refused",
+							reason: result.reason,
+							...(result.reasonCode === undefined ? {} : { reasonCode: result.reasonCode }),
+						}
+					: { type: "pending_stage_message_result", requestId, outcome: result.outcome },
+		);
+	}
+
+	respondPendingStageNotification(requestId: string, delivered: boolean): void {
+		writeMessage(this.requireActiveSocket(), { type: "pending_stage_notification_result", requestId, delivered });
+	}
+
   send(to: string, options: SendOptions): Promise<SendResult> {
     return this.sendFrame("send", to, options);
   }
 
+	sendPendingStageNotification(
+		runId: string,
+		capability: string,
+		to: string,
+		senderRegistrationName: string | undefined,
+		options: SendOptions,
+		senderReturnAddress?: string,
+	): Promise<SendResult> {
+		return this.sendFrame("send_pending_stage_notification", to, options, {
+			runId,
+			capability,
+			...(senderRegistrationName === undefined ? {} : { senderRegistrationName }),
+			...(senderReturnAddress === undefined ? {} : { senderReturnAddress }),
+		});
+	}
+
   sendToSupervisor(to: string, options: SendOptions): Promise<SendResult> {
     return this.sendFrame("supervisor_send", to, options);
   }
 
-  private sendFrame(type: "send" | "supervisor_send", to: string, options: SendOptions): Promise<SendResult> {
+	private sendFrame(
+		type: "send" | "supervisor_send" | "send_pending_stage_notification",
+		to: string,
+		options: SendOptions,
+		extra: {
+			readonly runId: string;
+			readonly capability: string;
+			readonly senderRegistrationName?: string;
+			readonly senderReturnAddress?: string;
+		} | undefined = undefined,
+	): Promise<SendResult> {
     let socket: net.Socket;
     try {
       socket = this.requireActiveSocket();
@@ -523,7 +713,7 @@ export class IntercomClient extends EventEmitter {
       content: { text: options.text, attachments: options.attachments },
     };
     try {
-      writeMessage(socket, { type, to, message, attemptId: acquired.attempt.attemptId });
+		writeMessage(socket, { type, to, message, attemptId: acquired.attempt.attemptId, ...extra });
     } catch (error) {
       this.pendingSends.reject(acquired.attempt, toError(error));
     }

package/dist/builtin/intercom/broker/pending-send-registry.ts

@@ -11,6 +11,10 @@ export interface SendResultLike {
   id: string;
   delivered: boolean;
   reason?: string;
+  queued?: boolean;
+  runId?: string;
+  stageKey?: string;
+  position?: number;
 }
 
 export interface PendingSendAttempt {

package/dist/builtin/intercom/broker/send-handler.ts

@@ -1,5 +1,6 @@
 import type net from "node:net";
-import type { Attachment, BrokerMessage, Message, SessionInfo } from "../types.js";
+import type { BrokerMessage, Message, SessionInfo } from "../types.js";
+import { isMessage } from "./client-message-validation.js";
 import { resolveSessionTarget, sessionTargetFailureReason } from "../session-target.js";
 import { DeliveredMessageCache } from "./delivered-message-cache.js";
 import { buildMessageSendSignature } from "./send-signature.js";
@@ -11,36 +12,60 @@ import { PendingQuestionIndex } from "./pending-question-index.js";
 export interface BrokerConnectedSession {
   socket: net.Socket;
   info: SessionInfo;
+  /**
+   * Immutable route authority from the host-admitted registration context.
+   * Model-accessible presence changes only `info.group`; they never rewrite this field.
+   * The local broker trusts initial registration metadata, matching all existing session fields.
+   */
+  readonly registrationGroup?: string;
+	/** Immutable registration-time name; mutable presence names never rewrite this reconnect alias. */
+	readonly registrationName?: string;
+	/** Opaque host-owned return identity; immutable after initial registration. */
+	readonly registrationReturnAddress?: string;
   /** Broker-bound supervisor relationship established by a capability. */
   supervisorId?: string;
   /** Private issuer identity used to restore child capabilities after reconnects. */
   supervisorOwnerToken?: string;
 }
 
-interface SendClientMessage extends Record<string, unknown> {
-  type: string;
+export interface PendingStageRoute {
+  readonly socket: net.Socket;
+  readonly from: BrokerConnectedSession;
+  readonly runId: string;
+  readonly stageKey: string;
+  readonly message: Message;
+  readonly attemptId?: string;
+	readonly liveTargetId?: string;
+	readonly signature?: string;
 }
 
-function isAttachment(value: unknown): value is Attachment {
-  if (typeof value !== "object" || value === null) return false;
-  const attachment = value as Record<string, unknown>;
-  if (attachment.type !== "file" && attachment.type !== "snippet" && attachment.type !== "context") return false;
-  if (typeof attachment.name !== "string" || typeof attachment.content !== "string") return false;
-  return attachment.language === undefined || typeof attachment.language === "string";
+export type PendingStageRouter = (route: PendingStageRoute) => boolean;
+
+export type LiveWorkflowStageResolver = (target: string) => BrokerConnectedSession | undefined;
+
+const WORKFLOW_RUN_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function parsePendingStageTarget(target: string): { runId: string; stageKey: string } | undefined {
+  const separator = target.indexOf(":");
+  if (separator < 0) return undefined;
+  const runId = target.slice(0, separator);
+  const stageKey = target.slice(separator + 1);
+  return WORKFLOW_RUN_ID_PATTERN.test(runId) && stageKey.length > 0 ? { runId, stageKey } : undefined;
 }
+export const PENDING_STAGE_ASK_REFUSAL =
+  "Cannot ask a workflow stage whose session has not initialized. Use send; Atomic will queue the message until the stage session initializes.";
+
 
-function isMessage(value: unknown): value is Message {
-  if (typeof value !== "object" || value === null) return false;
-  const message = value as Record<string, unknown>;
-  if (typeof message.id !== "string" || typeof message.timestamp !== "number") return false;
-  if (message.replyTo !== undefined && typeof message.replyTo !== "string") return false;
-  if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") return false;
-  if (typeof message.content !== "object" || message.content === null) return false;
-  const content = message.content as Record<string, unknown>;
-  if (typeof content.text !== "string") return false;
-  return content.attachments === undefined || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
+interface SendClientMessage extends Record<string, unknown> {
+  type: string;
+}
+function wireMessageId(value: unknown): string {
+  if (typeof value !== "object" || value === null) return "unknown";
+  const id = (value as Record<string, unknown>).id;
+  return typeof id === "string" ? id : "unknown";
 }
 
+
 /** Validate and route one wire-level send request. */
 export function handleBrokerSend(
   socket: net.Socket,
@@ -51,9 +76,11 @@ export function handleBrokerSend(
   write: (target: net.Socket, message: BrokerMessage) => void,
   supervisorCache: SupervisorChannelCache = new SupervisorChannelCache(),
   pendingQuestions: PendingQuestionIndex = new PendingQuestionIndex(),
+  routePendingStage?: PendingStageRouter,
+  resolveLiveWorkflowStage?: LiveWorkflowStageResolver,
 ): void {
   const message = clientMessage.message;
-  const messageId = isMessage(message) ? message.id : "unknown";
+  const messageId = wireMessageId(message);
   const hasAttemptId = Object.prototype.hasOwnProperty.call(clientMessage, "attemptId");
   if (hasAttemptId && typeof clientMessage.attemptId !== "string") {
     write(socket, {
@@ -74,27 +101,28 @@ export function handleBrokerSend(
   }
   const supervisorSend = clientMessage.type === "supervisor_send";
 
-  const signature = buildMessageSendSignature(clientMessage.to, message);
-  const deliveredMatch = deliveredMessages.lookup(message.id, signature);
-  if (deliveredMatch === "match") {
-    write(socket, { type: "delivered", messageId: message.id, attemptId });
-    return;
-  }
-  if (deliveredMatch === "conflict") {
-    write(socket, {
-      type: "delivery_failed",
-      messageId: message.id,
-      attemptId,
-      reason: `Intercom message ID '${message.id}' was already delivered with a different target or payload`,
-    });
-    return;
-  }
 
   const fromSession = currentId ? sessions.get(currentId) : undefined;
   if (!fromSession) {
     write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Sender session not found" });
     return;
   }
+	const signature = buildMessageSendSignature(clientMessage.to, message, fromSession.info.id);
+	const deliveredMatch = deliveredMessages.lookup(message.id, signature);
+	if (deliveredMatch === "match") {
+		write(socket, { type: "delivered", messageId: message.id, attemptId });
+		return;
+	}
+	if (deliveredMatch === "conflict") {
+		write(socket, {
+			type: "delivery_failed",
+			messageId: message.id,
+			attemptId,
+			reason: `Intercom message ID '${message.id}' was already delivered with a different target or payload`,
+			reasonCode: "message_id_conflict",
+		});
+		return;
+	}
   const trimmedTo = clientMessage.to.trim();
   if (supervisorSend && !fromSession.supervisorId) {
     write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Supervisor channel is not authorized" });
@@ -109,7 +137,8 @@ export function handleBrokerSend(
   // Exact-id targeting always resolves against the full pool so a cross-group id
   // is caught by the defense-in-depth group check below. Only a broker-authorized
   // supervisor frame or an exact recorded reply may resolve across groups.
-  const exactIdTarget = sessions.get(trimmedTo);
+	const liveWorkflowTarget = sessions.has(trimmedTo) ? undefined : resolveLiveWorkflowStage?.(trimmedTo);
+	const exactIdTarget = sessions.get(trimmedTo) ?? liveWorkflowTarget;
   const senderGroup = normalizeGroup(fromSession.info.group);
   const reachableAcrossGroups = supervisorSend || Boolean(message.replyTo);
   const candidates = reachableAcrossGroups
@@ -145,6 +174,22 @@ export function handleBrokerSend(
       });
       return;
     }
+		const liveTarget = parsePendingStageTarget(trimmedTo);
+		if (
+			liveWorkflowTarget !== undefined &&
+			liveTarget !== undefined &&
+			routePendingStage?.({
+				socket,
+				from: fromSession,
+				...liveTarget,
+				message,
+				...(attemptId ? { attemptId } : {}),
+				liveTargetId: target.info.id,
+				signature,
+			})
+		) {
+			return;
+		}
     write(target.socket, supervisorSend
       ? { type: "message", from: fromSession.info, message, channel: "supervisor" }
       : { type: "message", from: fromSession.info, message });
@@ -159,6 +204,15 @@ export function handleBrokerSend(
     write(socket, { type: "delivered", messageId: message.id, attemptId });
     return;
   }
+  if (resolution.kind === "not_found" && !supervisorSend && routePendingStage !== undefined) {
+    const pendingTarget = parsePendingStageTarget(trimmedTo);
+    if (
+      pendingTarget !== undefined &&
+      routePendingStage({ socket, from: fromSession, ...pendingTarget, message, ...(attemptId ? { attemptId } : {}) })
+    ) {
+      return;
+    }
+  }
   write(socket, {
     type: "delivery_failed",
     messageId: message.id,

package/dist/builtin/intercom/broker/send-signature.ts

@@ -29,12 +29,24 @@ export function buildSendSignature(to: string, options: LogicalSendOptions): str
   });
 }
 
-export function buildMessageSendSignature(to: string, message: Message): string {
-  return buildSendSignature(to, {
-    text: message.content.text,
-    attachments: message.content.attachments,
-    replyTo: message.replyTo,
-    expectsReply: message.expectsReply,
-    replyError: message.replyError,
-  });
+export function buildMessageSendSignature(to: string, message: Message, senderId?: string): string {
+	const logicalSignature = buildSendSignature(to, {
+		text: message.content.text,
+		attachments: message.content.attachments,
+		replyTo: message.replyTo,
+		expectsReply: message.expectsReply,
+		replyError: message.replyError,
+	});
+	if (senderId === undefined && message.source === undefined) return logicalSignature;
+	return JSON.stringify({
+		senderId: senderId ?? null,
+		logicalSignature,
+		source: message.source === undefined
+			? null
+			: {
+					subagentRunId: message.source.subagentRunId,
+					subagentAgent: message.source.subagentAgent ?? null,
+					subagentIndex: message.source.subagentIndex ?? null,
+				},
+	});
 }

package/dist/builtin/intercom/group.ts

@@ -0,0 +1,85 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+	subagentPolicy?: { intercomGroup?: string } | undefined;
+	/** Accepted from the live extension context but intentionally ignored for home resolution. */
+	sessionManager?: { getSessionId(): string } | undefined;
+}
+
+/**
+ * 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,
+): string {
+	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;
+}