@ctliz/agent-intercom-pi 0.12.0-connect.1 → 0.12.0-connect.4

package/README.md

@@ -4,7 +4,7 @@
 
 # Pi Intercom
 
-**Agent Intercom** is a cross-harness, same-machine messaging system for coding agents. Its Pi, Codex, Claude Code, and OpenCode adapters share one local broker and protocol, so sessions can discover and message each other regardless of which harness they run in.
+**Agent Intercom** is a cross-harness, same-machine messaging system for coding agents. Its Pi, Codex, Claude Code, OpenCode, Grok Build, and AGY adapters share one local broker and protocol, so sessions can discover and message each other regardless of which harness they run in.
 
 | Harness | Repository |
 |---|---|
@@ -13,8 +13,12 @@
 | Codex | [`agent-intercom-codex`](https://github.com/ctliz/agent-intercom-codex) |
 | Claude Code | [`agent-intercom-claude`](https://github.com/ctliz/agent-intercom-claude) |
 | OpenCode | [`agent-intercom-opencode`](https://github.com/ctliz/agent-intercom-opencode) |
+| Grok Build | [`agent-intercom-grok`](https://github.com/ctliz/agent-intercom-grok) |
+| AGY | [`agent-intercom-agy`](https://github.com/ctliz/agent-intercom-agy) |
 | Fleet lifecycle | [`agent-intercom-orchestrator`](https://github.com/ctliz/agent-intercom-orchestrator) |
 
+Grok Build and AGY use lightweight npm-packaged MCP launchers backed by the Claude MCP runtime. They retain inbound messages for `intercom_pending` polling but do not provide wake-on-message.
+
 ## Maintenance & Upstream Provenance
 
 - **Maintained by `ctliz`**: This distribution is maintained independently by [ctliz](https://github.com/ctliz).
@@ -61,7 +65,7 @@ Each pi session that has `pi-intercom` loaded and enabled connects to a tiny loc
 ## Install
 
 ```bash
-pi install git:github.com/ctliz/agent-intercom-pi@v0.11.0-connect.2
+pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.4
 ```
 
 If you are coming from `connect.1`, read [Upgrading from `connect.1`](#upgrading-from-connect1-to-connect2) first — the package namespace changed and the two versions must not be installed side by side.
@@ -71,7 +75,7 @@ Then restart Pi. The extension auto-connects to the broker on startup and regist
 On a supported Linux host (or WSL with a systemd user manager enabled) you can optionally install the orchestrator Pi plugin, which lets Pi create and safely own persistent Pi, Codex, Claude Code, and OpenCode coworkers. It is not required, and it is not available on macOS:
 
 ```bash
-pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.11.0-connect.2
+pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.2
 ```
 
 Restart Pi or run `/reload`, then verify:
@@ -85,7 +89,7 @@ The orchestrator package adds the `agent_fleet` tool, `/agents*` commands, a sco
 
 Pi loads the Intercom extension directly, including its native **Alt+I** contact-copy shortcut, so no wrapper command or shell alias is required. You can still alias your usual Pi invocation for convenience, but unlike adapters that need a wrapper to add terminal behavior, an alias does not enable any additional pi-intercom features.
 
-Pi-intercom is also protocol-compatible with the companion Codex, Claude, and OpenCode adapters. They share the same local broker and runtime directory, so sessions from all four hosts appear in the same session list and can send, ask, reply, and recover messages across host boundaries. The first connected adapter can start the broker; Pi does not need to be launched first.
+Pi-intercom is also protocol-compatible with the companion Codex, Claude, OpenCode, Grok Build, and AGY adapters. They share the same local broker and runtime directory, so sessions from all six hosts appear in the same session list and can send, ask, reply, and recover messages across host boundaries. The first connected adapter can start the broker; Pi does not need to be launched first.
 
 **Recommended:** Add this snippet to your project's `AGENTS.md` to help agents understand when to coordinate across sessions:
 
@@ -109,7 +113,7 @@ A session becomes intercom-connected when all of these are true:
 
 The session list only shows intercom-connected sessions, not every open Pi process on the machine.
 
-If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.11.0-connect.2` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.11.0-connect.2`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
+If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.4` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.2`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
 
 If `/intercom` still reports no peers, first confirm the other Pi windows have pi-intercom loaded and have also been reloaded. Open Pi processes without the extension, disabled sessions, and sessions using a different `PI_CODING_AGENT_DIR` intentionally do not appear in the same list.
 
@@ -218,6 +222,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,
@@ -591,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.
     });
@@ -616,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 };
@@ -655,7 +669,7 @@ 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) {
@@ -859,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];
@@ -2861,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.12.0-connect.1",
+  "version": "0.12.0-connect.4",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.ts",

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/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;
+}