@ctliz/agent-intercom-pi 0.11.0-connect.2 → 0.12.0-connect.3

package/README.md

@@ -218,6 +218,139 @@ Sender identity in `intercom:control.from.id` comes from the broker delivery fra
 
 The control bus is intentionally not exposed as a model-facing generic Intercom tool. Companion extensions expose only their specific, reviewed actions.
 
+## Teams, names, and who can talk to whom
+
+A **team** in Agent Intercom is the small group a session should treat as coworkers. It is not the same as the machine-wide session list. Agents that belong to a team should start with `intercom_team({})` and only fall back to `intercom_list({})` when they need an independently launched peer.
+
+`/name` is how a human gives a session a stable, speakable handle. The broker still identifies every session by a stable session ID; the name is the convenient address other agents should use when it is unique.
+
+### Name a session with `/name`
+
+`/name` is a Pi host command, not an Intercom command. After you set it, Intercom republishes the new name so other connected sessions can target it.
+
+```text
+# Terminal 1
+/name planner
+
+# Terminal 2
+/name worker
+
+# Terminal 3
+/name reviewer
+```
+
+Good names are short, unique in the same scope, and describe the role: `planner`, `api-worker`, `frontend-dev`. Avoid spaces. If two live sessions share the same name, prefer the short ID shown by `intercom_list` or the exact full session ID from `/intercom-id`.
+
+Check the published name:
+
+```typescript
+intercom_status({})
+intercom_list({})
+```
+
+Copy a host-neutral contact snippet for another agent:
+
+```text
+/intercom-id
+```
+
+That snippet uses the unique name when possible and falls back to the stable session ID when names collide.
+
+If you never set `/name`, Intercom still exposes a runtime-only fallback alias such as `subagent-chat-1a2b3c4d` so peers can reach the session. That alias is not stored as the Pi session title.
+
+### How `intercom_team` chooses a team
+
+`intercom_team({})` has no arguments. It resolves the current group in this order and stops at the first match:
+
+1. **Orchestrator** — `~/.pi/agent/intercom/orchestrator/workers.json` has an owned record for this session (`AGENT_INTERCOM_WORKER_ID`) or this session is the current manager of live owned coworkers.
+2. **TmuxDeck manifest** — `AGENT_INTERCOM_TEAM_MANIFEST` points at a valid team file. The Lead is `leadId`; workers are the other members. An invalid or empty manifest fails closed and does not fall through to the live roster.
+3. **Same-scope live roster** — `AGENT_INTERCOM_SCOPE_ID` is set. Coworkers are the other live non-human sessions in that scope. `AGENT_INTERCOM_MANAGER_TARGET` / `AGENT_INTERCOM_MANAGER_SESSION_ID` name the Lead when present.
+4. **Standalone** — no manager and no coworkers. Use `/name` plus `intercom_list` / `intercom_send` instead.
+
+Typical result:
+
+```text
+Manager: planner [connected]
+You: worker
+Coworkers:
+- reviewer target=reviewer (pi, worker, running) [connected]
+```
+
+Use the returned `target` with `intercom_send` and `intercom_ask`. After Orchestrator adoption, the manager target updates without restarting the worker. `AGENT_INTERCOM_MANAGER_TARGET` is only a startup fallback.
+
+Only an Orchestrator manager may inspect another session's pending inbox, and only with an exact connected coworker `target` from `intercom_team`:
+
+```typescript
+intercom_team({})
+intercom_pending({ session: "tmuxdeck-11111111-2222-4333-8444-555555555555" })
+```
+
+Manifest, live-roster, and standalone teams cannot inspect another session's inbox.
+
+### Join a TmuxDeck circle without becoming a Team Worker
+
+`/intercom-join` puts a standalone Pi session into an existing TmuxDeck workspace intercom circle. It is same-scope messaging only. It does **not** write a team manifest, does **not** enroll you as a Team Worker, and does **not** grant inbox inspection.
+
+```text
+/intercom-join                 # list joinable workspaces
+/intercom-join frontend        # join by exact workspace name
+/intercom-join 1               # join by the listed number
+/intercom-join --scope <48hex> # join by the workspace scope
+/intercom-status               # confirm membership and visible peers
+```
+
+Managed Team Workers and Orchestrator-owned sessions cannot join another circle. Listing never prints the raw scope.
+
+### Example: two-person billing team
+
+Open two terminals in the same repo and start Pi in each.
+
+```text
+# Terminal 1 — the person holding the plan
+/name planner
+intercom_status({})
+
+# Terminal 2 — the person making the change
+/name worker
+intercom_list({})
+```
+
+`intercom_list` should now show both `planner` and `worker`. If these terminals were launched inside the same TmuxDeck workspace, `intercom_team` also returns that pair as a live roster. Otherwise they are standalone peers that address each other by `/name`.
+
+Planner assigns work:
+
+```typescript
+intercom_send({
+  to: "worker",
+  message: "Add idempotent refund retries in src/billing/refunds.ts. Ask before changing the public error shape."
+})
+```
+
+Worker asks a blocking question, then reports done with `send`:
+
+```typescript
+intercom_ask({
+  to: "planner",
+  message: "Refunds currently return 500 on a mid-flight timeout. Should I map that to 409 Conflict?"
+})
+// planner replies in the triggered turn:
+intercom_reply({ message: "Yes. Keep the existing error body; only change the status code." })
+
+intercom_send({
+  to: "planner",
+  message: "Done. Timeouts now return 409. Tests in refunds.test.ts pass."
+})
+```
+
+If a third Pi is already running as `reviewer` in the same TmuxDeck workspace, join from a new standalone window without becoming a Team Worker:
+
+```text
+/intercom-join billing
+/name reviewer
+intercom_team({})
+intercom_send({ to: "planner", message: "I can review the refund retry once worker is done." })
+```
+
 ## Workflow: Planner-Worker Coordination
 
 The most natural use of pi-intercom is splitting a task between two sessions — one holds the big picture, the other does the hands-on work. When the worker hits an ambiguity ("should I optimize for readability or performance here?"), they ask without losing context.

package/broker/spawn.ts

@@ -173,6 +173,7 @@ export function getBrokerSpawnOptions(
   cwd: string;
   env: NodeJS.ProcessEnv;
   windowsHide: true;
+  shell: false;
 } {
   return {
     detached: true,
@@ -180,6 +181,7 @@ export function getBrokerSpawnOptions(
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
     windowsHide: true,
+    shell: false,
   };
 }
 

package/index.ts

@@ -7,7 +7,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { IntercomClient, type SendResult } from "./broker/client.ts";
 import { parseBossControl } from "./broker/boss-adapter.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
-import { intercomScopeIdFromEnvForRegistration } from "./protocol-v4/contract.ts";
+import { INTERCOM_SCOPE_ENV, intercomScopeIdFromEnvForRegistration } from "./protocol-v4/contract.ts";
 import { SessionListOverlay } from "./ui/session-list.ts";
 import { ComposeOverlay, type ComposeResult } from "./ui/compose.ts";
 import { InlineMessageComponent } from "./ui/inline-message.ts";
@@ -19,6 +19,19 @@ import { pendingAskId, ReplyTracker, type IntercomContext } from "./reply-tracke
 import { InboundMessageConflictError, PersistentInboundInbox, readPendingAsksSnapshot, type StoredInboundMessage } from "./inbound-inbox.ts";
 import { PersistentOutboundOutbox } from "./outbound-outbox.ts";
 import { formatIntercomTeam, resolveBossIntercomTeam, resolveIntercomTeam, resolveManagedInboxSession } from "./team.ts";
+import {
+  classifyMembership,
+  currentTmuxWorkspace,
+  formatJoinStatus,
+  formatJoinSuccess,
+  formatJoinableWorkspaceList,
+  isZhLocale,
+  listScopedWorkspaces,
+  parseJoinArgs,
+  readSessionScope,
+  rejectManagedJoin,
+  workspaceNameForScope,
+} from "./workspace-join.ts";
 import { authorizeBossSender, BossTeamScopeError, bossSelfSessionError, filterBossSessions, isBossControllerReadinessControl, readBossTeamScope, resolveBossLiveTarget } from "./boss-team-scope.ts";
 import {
   INTERCOM_CONTROL_DELIVERY_EVENT,
@@ -487,17 +500,50 @@ function parseSubagentIntercomPayload(payload: unknown): { to: string; message:
   const requestId = typeof record.requestId === "string" ? record.requestId : undefined;
   return { to: record.to, message: record.message, ...(requestId ? { requestId } : {}) };
 }
-function resolveIntercomPresenceName(sessionName: string | undefined, sessionId: string): string {
+
+const GENERIC_SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+export function resolveIntercomSessionId(
+  fallbackSessionId: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  const harnessSessionId = environment[INTERCOM_SESSION_ID_ENV]?.trim();
+  if (harnessSessionId) {
+    return harnessSessionId;
+  }
+  const genericSessionId = environment.AGENT_INTERCOM_SESSION_ID?.trim();
+  if (genericSessionId) {
+    if (!GENERIC_SESSION_ID_PATTERN.test(genericSessionId)) {
+      throw new Error("Invalid AGENT_INTERCOM_SESSION_ID: must match ^[A-Za-z0-9_-]{1,128}$");
+    }
+    return genericSessionId;
+  }
+  return fallbackSessionId;
+}
+
+export function resolveIntercomPresenceName(
+  sessionName: string | undefined,
+  sessionId: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
   const trimmedName = sessionName?.trim();
   if (trimmedName) {
     return trimmedName;
   }
+  const subagentName = environment[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
+  if (subagentName) {
+    return subagentName;
+  }
+  const genericName = environment.AGENT_INTERCOM_SESSION_NAME?.trim();
+  if (genericName) {
+    return genericName;
+  }
   const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
   return `${DEFAULT_UNNAMED_SESSION_ALIAS_PREFIX}-${normalizedSessionId.slice(0, 8)}`;
 }
-function buildPresenceIdentity(pi: ExtensionAPI, sessionId: string): { name: string } {
+function buildPresenceIdentity(pi: ExtensionAPI, sessionId: string, environment: NodeJS.ProcessEnv = process.env): { name: string } {
   return {
-    name: resolveIntercomPresenceName(pi.getSessionName(), sessionId),
+    name: resolveIntercomPresenceName(pi.getSessionName(), sessionId, environment),
   };
 }
 function formatSessionLabel(session: SessionInfo, duplicates: Set<string>, idPrefix: string): string {
@@ -558,11 +604,11 @@ interface ClipboardCopyResult {
 }
 
 function runDetachedClipboardCommand(command: string, args: string[], text: string): ClipboardCopyResult {
-  const found = spawnSync("which", [command], { stdio: "ignore", timeout: 1000 });
+  const found = spawnSync("which", [command], { stdio: "ignore", timeout: 1000, shell: false });
   if (found.status !== 0) return { ok: false, error: `${command} not found` };
 
   try {
-    const proc = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+    const proc = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
     proc.stdin.on("error", () => {
       // Ignore EPIPE if the clipboard helper exits early.
     });
@@ -583,6 +629,7 @@ function runClipboardCommand(command: string, args: string[], text: string): Cli
     encoding: "utf8",
     timeout: 2000,
     stdio: ["pipe", "ignore", "pipe"],
+    shell: false,
   });
   if (result.status === 0) return { ok: true, method: command };
   if (result.error) return { ok: false, error: result.error.message };
@@ -622,7 +669,15 @@ function getNamePollMs(): number {
   return 1000;
 }
 export default function piIntercomExtension(pi: ExtensionAPI) {
-  const runtimeScopeId = intercomScopeIdFromEnvForRegistration();
+  let runtimeScopeId = intercomScopeIdFromEnvForRegistration();
+  const initialHarnessSessionId = process.env[INTERCOM_SESSION_ID_ENV]?.trim();
+  const initialGenericSessionId = process.env.AGENT_INTERCOM_SESSION_ID?.trim();
+  if (initialGenericSessionId && !initialHarnessSessionId) {
+    if (!GENERIC_SESSION_ID_PATTERN.test(initialGenericSessionId)) {
+      throw new Error("Invalid AGENT_INTERCOM_SESSION_ID: must match ^[A-Za-z0-9_-]{1,128}$");
+    }
+  }
+  const configuredSessionId = initialHarnessSessionId || initialGenericSessionId;
   let client: IntercomClient | null = null;
   const config: IntercomConfig = loadConfig();
   const bossTeamScope = readBossTeamScope();
@@ -739,8 +794,11 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       return null;
     }
     try {
-      if (currentSessionId && ctx.sessionManager.getSessionId() !== currentSessionId) {
-        return null;
+      if (currentSessionId) {
+        const expectedSessionId = configuredSessionId || ctx.sessionManager.getSessionId();
+        if (expectedSessionId !== currentSessionId) {
+          return null;
+        }
       }
       void ctx.hasUI;
       return ctx;
@@ -789,11 +847,12 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       ...(runtimeInstanceId ? { runtimeInstanceId } : {}),
     };
   }
-  function syncPresenceIdentity(sessionId: string): void {
+  function syncPresenceIdentity(sessionId?: string): void {
     if (!client || !getLiveContext()) {
       return;
     }
-    const identity = buildPresenceIdentity(pi, sessionId);
+    const resolvedId = currentSessionId ?? (configuredSessionId || (sessionId ? sessionId : "default"));
+    const identity = buildPresenceIdentity(pi, resolvedId);
     lastPresenceName = identity.name;
     client.updatePresence({ ...identity, status: currentStatus() });
   }
@@ -814,6 +873,20 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   function publishIntercomSessionId(sessionId: string): void {
     process.env[INTERCOM_SESSION_ID_ENV] = sessionId;
   }
+  async function switchRuntimeScope(nextScopeId: string): Promise<void> {
+    if (runtimeScopeId === nextScopeId && process.env[INTERCOM_SCOPE_ENV] === nextScopeId) {
+      return;
+    }
+    runtimeScopeId = nextScopeId;
+    process.env[INTERCOM_SCOPE_ENV] = nextScopeId;
+    const previousClient = client;
+    client = null;
+    if (previousClient) {
+      await previousClient.disconnect(true).catch(() => undefined);
+    }
+    await ensureConnected("tool");
+  }
+
   function restoreIntercomSessionId(): void {
     if (previousIntercomSessionId === undefined) {
       delete process.env[INTERCOM_SESSION_ID_ENV];
@@ -1343,7 +1416,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     rejectAllReplyWaiters(new Error("Session replaced"));
     replyTracker.reset();
     runtimeContext = ctx;
-    currentSessionId = ctx.sessionManager.getSessionId();
+    currentSessionId = configuredSessionId || ctx.sessionManager.getSessionId();
+    publishIntercomSessionId(currentSessionId);
     if (bossTeamScope.present && bossSelfSessionError(bossTeamScope, currentSessionId)) {
       const staleOutbox = new PersistentOutboundOutbox(currentSessionId);
       const removed = staleOutbox.list().length;
@@ -1666,7 +1740,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     scheduleInboundFlush(0);
   });
   pi.on("turn_start", (_event, ctx) => {
-    const sessionId = ctx.sessionManager.getSessionId();
+    const rawSessionId = ctx.sessionManager.getSessionId();
+    const sessionId = configuredSessionId || rawSessionId;
     if (!currentSessionId || sessionId !== currentSessionId) {
       if (!config.enabled) {
         return;
@@ -1688,7 +1763,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     currentModel = event.model.id;
     if (client) {
       client.updatePresence({
-        ...buildPresenceIdentity(pi, ctx.sessionManager.getSessionId()),
+        ...buildPresenceIdentity(pi, currentSessionId ?? (configuredSessionId || ctx.sessionManager.getSessionId())),
         model: event.model.id,
         status: currentStatus(),
       });
@@ -2814,6 +2889,107 @@ Usage:
     },
   });
 
+  pi.registerCommand("intercom-join", {
+    description: "Join an existing TmuxDeck workspace intercom circle. This does not enroll you as a Team Worker.",
+    handler: async (args, ctx) => {
+      const zh = isZhLocale();
+      const fail = (workspace?: string) => {
+        notifyIfLive(ctx, workspace
+          ? (zh
+            ? `无法加入工作区 ${workspace} 的通话圈。`
+            : `Could not join the intercom circle for workspace ${workspace}.`)
+          : (zh ? "无法加入该工作区通话圈。" : "Could not join that workspace intercom circle."), "error");
+      };
+      try {
+        const blocked = rejectManagedJoin(classifyMembership(), zh);
+        if (blocked) {
+          notifyIfLive(ctx, blocked, "error");
+          return;
+        }
+        const parsed = parseJoinArgs(args);
+        const workspaces = await listScopedWorkspaces();
+        let workspace: string | undefined;
+        if (parsed.kind === "list") {
+          notifyIfLive(ctx, formatJoinableWorkspaceList({ workspaces, zh }), "info");
+          return;
+        }
+        if (parsed.kind === "index" && parsed.index) {
+          const selected = workspaces[parsed.index - 1];
+          if (!selected) {
+            notifyIfLive(ctx, zh
+              ? "没有这个编号的工作区。"
+              : "No workspace uses that number.", "error");
+            return;
+          }
+          workspace = selected.sessionName;
+        } else if (parsed.kind === "workspace" && parsed.workspace) {
+          workspace = parsed.workspace;
+        } else if (parsed.kind === "scope" && parsed.scope) {
+          workspace = await workspaceNameForScope(parsed.scope);
+          if (!workspace) {
+            fail();
+            return;
+          }
+        }
+        if (!workspace) {
+          fail();
+          return;
+        }
+        const scope = await readSessionScope(workspace);
+        if (!scope) {
+          fail(workspace);
+          return;
+        }
+        if (!getLiveContext(ctx)) {
+          startSessionRuntime(ctx);
+        }
+        await switchRuntimeScope(scope);
+        syncPresenceIdentity(currentSessionId ?? ctx.sessionManager.getSessionId());
+        const displayName = currentSessionId
+          ? buildPresenceIdentity(pi, currentSessionId).name
+          : (pi.getSessionName()?.trim() || "unnamed");
+        notifyIfLive(ctx, formatJoinSuccess({
+          workspace,
+          name: displayName,
+          zh,
+        }), "info");
+      } catch (error) {
+        notifyIfLive(ctx, getErrorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("intercom-status", {
+    description: "Show whether this session is standalone, same-scope, tmuxdeck-team, or orchestrator.",
+    handler: async (_args, ctx) => {
+      const zh = isZhLocale();
+      try {
+        const membership = classifyMembership();
+        const workspace = await currentTmuxWorkspace()
+          ?? (runtimeScopeId ? await workspaceNameForScope(runtimeScopeId) : undefined);
+        const displayName = currentSessionId
+          ? buildPresenceIdentity(pi, currentSessionId).name
+          : (pi.getSessionName()?.trim() || "unnamed");
+        let peers: string[] = [];
+        if (client?.isConnected()) {
+          const sessions = await client.listSessions();
+          peers = sessions
+            .filter((session) => session.id !== client?.sessionId && session.model !== "human")
+            .map((session) => session.name || session.id);
+        }
+        notifyIfLive(ctx, formatJoinStatus({
+          membership,
+          workspace,
+          name: displayName,
+          peers,
+          zh,
+        }), "info");
+      } catch (error) {
+        notifyIfLive(ctx, getErrorMessage(error), "error");
+      }
+    },
+  });
+
   pi.registerShortcut("alt+m", {
     description: "Open session intercom",
     handler: async (ctx) => openIntercomOverlay(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.11.0-connect.2",
+  "version": "0.12.0-connect.3",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.ts",
@@ -44,7 +44,7 @@
     ]
   },
   "dependencies": {
-    "@ctliz/agent-intercom-core": "git+https://github.com/ctliz/agent-intercom-core.git#37e074970e2a9de32a16fc325607c3b476b0bd45",
+    "@ctliz/agent-intercom-core": "0.2.0",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",

package/skills/pi-intercom/SKILL.md

@@ -397,6 +397,15 @@ Use `/name` so others can target you easily:
 /name planner
 ```
 
+To join an existing TmuxDeck workspace intercom circle without becoming a Team Worker:
+
+```
+/intercom-join frontend
+/intercom-status
+```
+
+`/intercom-join` with no argument lists available TmuxDeck workspaces. Joining is same-scope messaging only; it does not enroll you as a Team Worker.
+
 ## Error Handling
 
 ### Common Errors and Solutions

package/team.ts

@@ -1,11 +1,13 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { readTeamManifest, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 import { getAgentDirPath } from "./broker/paths.ts";
 import { bossSelfSessionError, resolveBossLiveSession, type BossTeamScope } from "./boss-team-scope.ts";
 
 export interface TeamSession {
   id: string;
   name?: string;
+  model?: string;
   origin?: "local" | "remote";
 }
 
@@ -29,9 +31,12 @@ export interface TeamMember {
   connected: boolean;
 }
 
+export type IntercomTeamSource = "orchestrator" | "manifest" | "live_roster" | "standalone";
+
 export interface IntercomTeam {
+  source: IntercomTeamSource;
   teamId?: string;
-  self: { id: string; workerId?: string; isManager: boolean };
+  self: { id: string; workerId?: string; isManager: boolean; role?: string };
   manager?: { target: string; connected: boolean };
   controller?: { target: string; connected: boolean };
   coworkers: TeamMember[];
@@ -46,6 +51,9 @@ export function resolveManagedInboxSession(input: {
   if (!input.team.self.isManager) {
     throw new Error("Only a manager may inspect another session's pending-ask inbox");
   }
+  if (input.team.source !== "orchestrator") {
+    throw new Error("Pending-ask inbox inspection is only available for orchestrator-managed teams");
+  }
   const member = input.team.coworkers.find((entry) => entry.target === input.requestedSession);
   if (!member) {
     throw new Error(`Pending-ask inbox access denied for "${input.requestedSession}"; select an owned coworker target returned by intercom_team`);
@@ -80,6 +88,13 @@ async function readWorkers(agentDir: string): Promise<StoredWorker[]> {
   }
 }
 
+/**
+ * Resolves the Intercom team following the exact priority hierarchy:
+ * 1. Authoritative Orchestrator record in workers.json (matching AGENT_INTERCOM_WORKER_ID or active manager ownership)
+ * 2. Explicit TmuxDeck Manifest (AGENT_INTERCOM_TEAM_MANIFEST)
+ * 3. Workspace Live Same-Scope Non-Human Roster Fallback (AGENT_INTERCOM_SCOPE_ID present)
+ * 4. Standalone unmanaged session
+ */
 export async function resolveIntercomTeam(input: {
   selfId: string;
   sessions: TeamSession[];
@@ -93,39 +108,184 @@ export async function resolveIntercomTeam(input: {
   const current = workerId
     ? workers.find((worker) => stringValue(worker.id) === workerId && (!runId || stringValue(worker.runId) === runId))
     : undefined;
-  const managerTarget = stringValue(current?.managerSessionId) ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
-  const teamId = managerTarget ?? input.selfId;
-  const isManager = !managerTarget;
-  const coworkers = workers
-    .filter((worker) => worker.owned === true)
-    .filter((worker) => stringValue(worker.managerSessionId) === teamId)
-    .filter((worker) => LIVE_STATES.has(stringValue(worker.state) ?? ""))
-    .filter((worker) => stringValue(worker.id) !== workerId)
-    .map((worker): TeamMember | undefined => {
-      const id = stringValue(worker.id);
-      if (!id) return undefined;
-      const target = stringValue(worker.intercomTarget) ?? id;
+
+  // 1. Authoritative Orchestrator Record
+  if (current) {
+    const managerTarget =
+      stringValue(current.managerSessionId) ??
+      stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ??
+      stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+
+    const coworkers: TeamMember[] = managerTarget
+      ? workers
+          .filter((worker) => worker.owned === true)
+          .filter((worker) => stringValue(worker.managerSessionId) === managerTarget)
+          .filter((worker) => LIVE_STATES.has(stringValue(worker.state) ?? ""))
+          .filter((worker) => stringValue(worker.id) !== workerId)
+          .map((worker): TeamMember | undefined => {
+            const id = stringValue(worker.id);
+            if (!id) return undefined;
+            const target = stringValue(worker.intercomTarget) ?? id;
+            return {
+              id,
+              target,
+              ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+              ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+              ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+              connected: connectedTo(input.sessions, target),
+            };
+          })
+          .filter((member): member is TeamMember => Boolean(member))
+      : [];
+
+    return {
+      source: "orchestrator",
+      ...(managerTarget ? { teamId: managerTarget } : {}),
+      self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
+      ...(managerTarget
+        ? { manager: { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) } }
+        : {}),
+      coworkers,
+    };
+  }
+
+  if (workerId === undefined && input.selfId) {
+    const managerOwnedCoworkers = workers
+      .filter((worker) => worker.owned === true)
+      .filter((worker) => stringValue(worker.managerSessionId) === input.selfId)
+      .filter((worker) => LIVE_STATES.has(stringValue(worker.state) ?? ""))
+      .map((worker): TeamMember | undefined => {
+        const id = stringValue(worker.id);
+        if (!id) return undefined;
+        const target = stringValue(worker.intercomTarget) ?? id;
+        return {
+          id,
+          target,
+          ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+          ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+          ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+          connected: connectedTo(input.sessions, target),
+        };
+      })
+      .filter((member): member is TeamMember => Boolean(member));
+
+    if (managerOwnedCoworkers.length > 0) {
       return {
-        id,
-        target,
-        ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
-        ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
-        ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
-        connected: connectedTo(input.sessions, target),
+        source: "orchestrator",
+        teamId: input.selfId,
+        self: { id: input.selfId, isManager: true },
+        manager: { target: input.selfId, connected: true },
+        coworkers: managerOwnedCoworkers,
       };
-    })
-    .filter((member): member is TeamMember => Boolean(member));
+    }
+  }
 
+  // 2. Explicit TmuxDeck Team Manifest
+  if (env.AGENT_INTERCOM_TEAM_MANIFEST !== undefined) {
+    const rawManifestPath = env.AGENT_INTERCOM_TEAM_MANIFEST;
+    if (typeof rawManifestPath !== "string" || !rawManifestPath.trim()) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const manifest = readTeamManifest(rawManifestPath.trim());
+    if (!manifest) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+
+    const selfMember = manifest.members.find((member) => member.sessionId === input.selfId);
+    if (!selfMember) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+
+    const isManager = input.selfId === manifest.leadId;
+    const managerTarget = manifest.leadId;
+
+    // Coworkers:
+    // Lead: all workers
+    // Worker: other workers (excluding self and excluding Lead/manager)
+    const coworkers: TeamMember[] = manifest.members
+      .filter((member) => member.sessionId !== input.selfId && member.sessionId !== manifest.leadId)
+      .map((member) => ({
+        id: member.sessionId,
+        target: member.sessionId,
+        role: member.role,
+        connected: connectedTo(input.sessions, member.sessionId),
+      }));
+
+    return {
+      source: "manifest",
+      teamId: manifest.runId,
+      self: {
+        id: input.selfId,
+        isManager,
+        role: selfMember.role,
+      },
+      manager: { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) },
+      coworkers,
+    };
+  }
+
+  // 3. Workspace Live Same-Scope Non-Human Roster Fallback
+  const scopeId = stringValue(env.AGENT_INTERCOM_SCOPE_ID);
+  if (scopeId !== undefined) {
+    const managerTarget =
+      stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ??
+      stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+    const isManager = !managerTarget || managerTarget === input.selfId;
+    const effectiveManagerTarget = isManager ? input.selfId : managerTarget;
+
+    const coworkers: TeamMember[] = input.sessions
+      .filter((session) => session.id !== input.selfId)
+      .filter((session) => session.model !== "human")
+      .filter((session) => isManager || session.id !== effectiveManagerTarget)
+      .map((session) => ({
+        id: session.id,
+        target: session.id,
+        connected: true,
+      }));
+
+    return {
+      source: "live_roster",
+      teamId: effectiveManagerTarget,
+      self: { id: input.selfId, isManager },
+      manager: {
+        target: effectiveManagerTarget,
+        connected: connectedTo(input.sessions, effectiveManagerTarget),
+      },
+      coworkers,
+    };
+  }
+
+  // 4. Standalone Session Fallback
   return {
-    teamId,
-    self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager },
-    manager: managerTarget
-      ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) }
-      : { target: input.selfId, connected: true },
-    coworkers,
+    source: "standalone",
+    self: { id: input.selfId, isManager: false },
+    coworkers: [],
   };
 }
 
+export function formatIntercomTeam(team: IntercomTeam): string {
+  const manager = team.manager
+    ? `${team.manager.target} [${team.manager.connected ? "connected" : "not connected"}]`
+    : "unknown";
+  const lines = [
+    `Manager: ${manager}`,
+    `You: ${team.self.id}${team.self.isManager ? " [manager]" : ""}`,
+  ];
+  if (team.controller) {
+    lines.push(`Controller: ${team.controller.target} [connected]`);
+  }
+  if (team.coworkers.length === 0) {
+    lines.push("Coworkers: none");
+  } else {
+    lines.push("Coworkers:");
+    for (const coworker of team.coworkers) {
+      const metadata = [coworker.harness, coworker.role, coworker.state].filter(Boolean).join(", ");
+      lines.push(`- ${coworker.id} target=${coworker.target}${metadata ? ` (${metadata})` : ""} [${coworker.connected ? "connected" : "not connected"}]`);
+    }
+  }
+  return lines.join("\n");
+}
+
 export function resolveBossIntercomTeam(input: {
   selfId: string;
   sessions: TeamSession[];
@@ -160,6 +320,7 @@ export function resolveBossIntercomTeam(input: {
   }
 
   return {
+    source: "orchestrator",
     ...(manager ? { teamId: manager.target } : {}),
     self: { id: input.selfId, isManager },
     ...(manager ? { manager } : {}),
@@ -167,26 +328,3 @@ export function resolveBossIntercomTeam(input: {
     coworkers,
   };
 }
-
-export function formatIntercomTeam(team: IntercomTeam): string {
-  const manager = team.manager
-    ? `${team.manager.target} [${team.manager.connected ? "connected" : "not connected"}]`
-    : "unknown";
-  const lines = [
-    `Manager: ${manager}`,
-    `You: ${team.self.id}${team.self.isManager ? " [manager]" : ""}`,
-  ];
-  if (team.controller) {
-    lines.push(`Controller: ${team.controller.target} [connected]`);
-  }
-  if (team.coworkers.length === 0) {
-    lines.push("Coworkers: none");
-  } else {
-    lines.push("Coworkers:");
-    for (const coworker of team.coworkers) {
-      const metadata = [coworker.harness, coworker.role, coworker.state].filter(Boolean).join(", ");
-      lines.push(`- ${coworker.id} target=${coworker.target}${metadata ? ` (${metadata})` : ""} [${coworker.connected ? "connected" : "not connected"}]`);
-    }
-  }
-  return lines.join("\n");
-}

package/workspace-join.ts

@@ -0,0 +1,235 @@
+import { execFile } from "node:child_process";
+import { INTERCOM_SCOPE_ENV } from "./protocol-v4/contract.ts";
+
+export type JoinMembership = "standalone" | "same-scope" | "tmuxdeck-team" | "orchestrator";
+
+export type ScopedWorkspace = {
+  sessionName: string;
+  scopeId: string;
+};
+
+export type TmuxExec = (
+  args: string[],
+  env?: NodeJS.ProcessEnv,
+) => Promise<{ ok: boolean; stdout: string }>;
+
+export interface ParsedJoinArgs {
+  kind: "list" | "workspace" | "index" | "scope";
+  workspace?: string;
+  index?: number;
+  scope?: string;
+}
+
+export function isTmuxDeckScope(value: string): boolean {
+  if (value.length !== 48) return false;
+  for (const char of value) {
+    if (!((char >= "0" && char <= "9") || (char >= "a" && char <= "f"))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function isZhLocale(env: NodeJS.ProcessEnv = process.env): boolean {
+  const locale = `${env.LC_ALL || env.LC_MESSAGES || env.LANG || ""}`.toLowerCase();
+  return locale.startsWith("zh");
+}
+
+export function parseJoinArgs(raw: string): ParsedJoinArgs {
+  const args = raw.trim().split(/\s+/).filter(Boolean);
+  if (args.length === 0) {
+    return { kind: "list" };
+  }
+  if (args[0] === "--scope") {
+    if (args.length !== 2 || !args[1]) {
+      throw new Error(isZhLocale()
+        ? "用法：/intercom-join --scope <48 hex>"
+        : "Usage: /intercom-join --scope <48 hex>");
+    }
+    return { kind: "scope", scope: parseJoinScope(args[1]) };
+  }
+  if (args.length !== 1 || args[0].startsWith("-")) {
+    throw new Error(isZhLocale()
+      ? "用法：/intercom-join [工作区名或编号] 或 /intercom-join --scope <48 hex>"
+      : "Usage: /intercom-join [workspace or number] or /intercom-join --scope <48 hex>");
+  }
+  if (/^[1-9]\d*$/.test(args[0])) {
+    return { kind: "index", index: Number(args[0]) };
+  }
+  return { kind: "workspace", workspace: args[0] };
+}
+
+export function parseJoinScope(value: string): string {
+  if (!isTmuxDeckScope(value)) {
+    throw new Error(isZhLocale()
+      ? "无法加入该工作区通话圈。"
+      : "Could not join that workspace intercom circle.");
+  }
+  return value;
+}
+
+export function classifyMembership(env: NodeJS.ProcessEnv = process.env): JoinMembership {
+  if (env.AGENT_INTERCOM_WORKER_ID?.trim() || env.AGENT_INTERCOM_OWNED === "1") {
+    return "orchestrator";
+  }
+  if (env.AGENT_INTERCOM_TEAM_MANIFEST?.trim()) {
+    return "tmuxdeck-team";
+  }
+  if (env.AGENT_INTERCOM_SCOPE_ID?.trim()) {
+    return "same-scope";
+  }
+  return "standalone";
+}
+
+export function parseTmuxEnvironmentStdout(stdout: string, varName = INTERCOM_SCOPE_ENV): string | undefined {
+  const unsetMarker = `-${varName}`;
+  const prefix = `${varName}=`;
+  for (const line of stdout.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === unsetMarker) {
+      return undefined;
+    }
+    if (trimmed.startsWith(prefix)) {
+      const value = trimmed.slice(prefix.length).trim();
+      return value || undefined;
+    }
+  }
+  return undefined;
+}
+
+export function defaultExecTmux(args: string[], env: NodeJS.ProcessEnv = process.env): Promise<{ ok: boolean; stdout: string }> {
+  return new Promise((resolve) => {
+    execFile("tmux", args, { encoding: "utf8", timeout: 2000, env, shell: false }, (error, stdout) => {
+      if (error) {
+        resolve({ ok: false, stdout: "" });
+        return;
+      }
+      resolve({ ok: true, stdout: stdout ?? "" });
+    });
+  });
+}
+
+export const tmuxRuntime = {
+  exec: defaultExecTmux as TmuxExec,
+};
+
+export async function listScopedWorkspaces(options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<ScopedWorkspace[]> {
+  const env = options.env ?? process.env;
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const listed = await execTmux(["list-sessions", "-F", "#{session_name}"], env);
+  if (!listed.ok) {
+    return [];
+  }
+  const names = listed.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const workspaces: ScopedWorkspace[] = [];
+  for (const sessionName of names) {
+    const scopeId = await readSessionScope(sessionName, { env, execTmux });
+    if (scopeId) {
+      workspaces.push({ sessionName, scopeId });
+    }
+  }
+  return workspaces;
+}
+
+export async function readSessionScope(sessionName: string, options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  const env = options.env ?? process.env;
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const shown = await execTmux(["show-environment", "-t", sessionName, INTERCOM_SCOPE_ENV], env);
+  if (!shown.ok) {
+    return undefined;
+  }
+  const raw = parseTmuxEnvironmentStdout(shown.stdout);
+  if (!raw || !isTmuxDeckScope(raw)) {
+    return undefined;
+  }
+  return raw;
+}
+
+export async function workspaceNameForScope(scope: string, options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  for (const workspace of await listScopedWorkspaces(options)) {
+    if (workspace.scopeId === scope) {
+      return workspace.sessionName;
+    }
+  }
+  return undefined;
+}
+
+export async function currentTmuxWorkspace(options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  const env = options.env ?? process.env;
+  if (!env.TMUX?.trim()) {
+    return undefined;
+  }
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const shown = await execTmux(["display-message", "-p", "#S"], env);
+  const name = shown.stdout.trim();
+  return name || undefined;
+}
+
+export function formatJoinableWorkspaceList(input: {
+  workspaces: Array<{ sessionName: string }>;
+  zh: boolean;
+}): string {
+  if (input.workspaces.length === 0) {
+    return input.zh
+      ? "没有找到带通话圈的 TmuxDeck 工作区。"
+      : "No scoped TmuxDeck workspaces found.";
+  }
+  const header = input.zh ? "可加入的 TmuxDeck 工作区：" : "Available TmuxDeck workspaces:";
+  const footer = input.zh
+    ? "请输入编号或精确工作区名（Ctrl-C 取消）："
+    : "Select a workspace by number or exact name (Ctrl-C to cancel):";
+  return [
+    header,
+    ...input.workspaces.map((workspace, index) => `  ${index + 1}) ${workspace.sessionName}`),
+    footer,
+  ].join("\n");
+}
+
+export function formatJoinSuccess(input: { workspace: string; name: string; zh: boolean }): string {
+  return input.zh
+    ? `已加入工作区 ${input.workspace} 的通话圈。\n身份：外部协作者（不是 Team Worker）\n你的显示名：${input.name}`
+    : `Joined the intercom circle for workspace ${input.workspace}.\nRole: external collaborator (not a Team Worker)\nDisplay name: ${input.name}`;
+}
+
+export function formatJoinStatus(input: {
+  membership: JoinMembership;
+  workspace?: string;
+  name: string;
+  peers: string[];
+  zh: boolean;
+}): string {
+  return input.zh
+    ? [
+      input.membership,
+      `工作区：${input.workspace || "无"}`,
+      `显示名：${input.name}`,
+      `同圈可见：${input.peers.length > 0 ? input.peers.join(", ") : "无"}`,
+    ].join("\n")
+    : [
+      input.membership,
+      `Workspace: ${input.workspace || "none"}`,
+      `Display name: ${input.name}`,
+      `Visible in circle: ${input.peers.length > 0 ? input.peers.join(", ") : "none"}`,
+    ].join("\n");
+}
+
+export function rejectManagedJoin(membership: JoinMembership, zh: boolean): string | undefined {
+  if (membership === "tmuxdeck-team" || membership === "orchestrator") {
+    return zh
+      ? "当前会话已是正式成员，不能再加入其他工作区通话圈。"
+      : "This session is already a managed member and cannot join another workspace circle.";
+  }
+  return undefined;
+}