tmux-ide 2.9.0-beta.47 → 2.9.0-beta.49

package/packages/daemon/src/command-center/resources/application-shell.ts

@@ -1,3 +1,5 @@
+import type { PaneTeamMembership } from "@tmux-ide/contracts";
+import { resolvePaneDisplayName } from "../../terminal/protocol/pane-display-name.ts";
 import type { NativePaneIdentity } from "@tmux-ide/contracts";
 import { hostname } from "node:os";
 import { basename } from "node:path";
@@ -44,6 +46,7 @@ export interface ApplicationShellPanePresentationFacts {
   readonly active: boolean;
   readonly role: string | null;
   readonly name: string | null;
+  readonly nameSource?: string | null;
   readonly type: string | null;
   /** Stable detected agent kind; private discovery fact, never a wire identity. */
   readonly agentKind?: string | null;
@@ -69,6 +72,8 @@ export interface ApplicationShellPanePresentationFacts {
   readonly agentStatusTextRaw?: string | null;
   /** Raw `@agent_display_name`; sanitized + freshness-gated in the pure layer. */
   readonly agentDisplayNameRaw?: string | null;
+  readonly teamMemberName?: string;
+  readonly team?: PaneTeamMembership;
   /**
    * Screen-scrape fallback verdict the discovery layer resolved for panes
    * WITHOUT fresh authority. `null` means authority was fresh (scrape skipped);
@@ -384,6 +389,7 @@ function deprecatedStandalonePaneIdentities(
 export function harnessForPane(
   pane: ApplicationShellPanePresentationFacts,
 ): "codex" | "claude-code" | "custom" {
+  if (pane.teamMemberName) return "claude-code";
   const detected = pane.agentKind?.toLowerCase();
   if (detected === "codex") return "codex";
   if (detected === "claude" || detected === "claude-code") return "claude-code";
@@ -393,42 +399,41 @@ export function harnessForPane(
   return "custom";
 }
 
-const GENERIC_PANE_LABELS = new Set(["shell", "terminal", "tmux"]);
-
-function isGenericPaneLabel(value: string | null | undefined): boolean {
-  const normalized = value?.trim().toLowerCase() ?? "";
-  return normalized.length === 0 || GENERIC_PANE_LABELS.has(normalized);
-}
-
 /**
  * A promoted configless pane can be stamped as `Terminal` before the native
  * inventory's process-tree pass resolves a wrapped/version-shaped agent
  * executable. Once that stronger identity exists, do not keep publishing the
  * provisional generic label into the sidebar and pane chrome.
  */
-function resolvedAgentLabel(
+export function resolvedAgentLabel(
   pane: ApplicationShellPanePresentationFacts,
   presentation: ResolvedAgentPresentation,
   index: number,
 ): string {
-  if (presentation.displayName !== undefined) {
-    return label(presentation.displayName, `Agent ${index + 1}`);
-  }
-  if (!isGenericPaneLabel(pane.name)) return label(pane.name, `Agent ${index + 1}`);
-
+  const resolved = resolvePaneDisplayName({
+    semanticPaneId: pane.semanticPaneId ?? `agent.${index}`,
+    configuredName: pane.name,
+    configuredNameSource: pane.nameSource,
+    agentDisplayName: presentation.displayName,
+    teamMemberName: pane.teamMemberName,
+    currentCommand: pane.currentCommand,
+    title: pane.title,
+    hostName: hostname(),
+  });
+  if (["manual", "agent", "title"].includes(resolved.source))
+    return label(resolved.name, `Agent ${index + 1}`);
   const harness = harnessForPane(pane);
   if (harness === "codex") return "Codex";
   if (harness === "claude-code") return "Claude Code";
-
-  if (!isGenericPaneLabel(pane.title) && !isHostNameTitle(pane.title, hostname())) {
-    return label(pane.title, `Agent ${index + 1}`);
-  }
-  return `Agent ${index + 1}`;
+  return resolved.source === "process"
+    ? label(resolved.name, `Agent ${index + 1}`)
+    : `Agent ${index + 1}`;
 }
 
 const AGENT_STATE_STAMP = /^(?:working|blocked|done|idle):\d+$/u;
 
 export function isAgentPane(pane: ApplicationShellPanePresentationFacts): boolean {
+  if (pane.teamMemberName || pane.team) return true;
   // A well-formed @agent_state stamp IS the agent contract: any pane that
   // self-reports is an agent pane, even when its command is a bare shell and
   // no @ide_type/role metadata exists. Staleness only affects the status, not
@@ -627,6 +632,7 @@ function projectApplicationShellResourceV1Core(
         // labels such as `Terminal` with the canonical harness name.
         name: resolvedAgentLabel(pane, presentation, index),
         harness: harnessForPane(pane),
+        ...(pane.team ? { team: pane.team } : {}),
         activity: presentation.activity,
         paneId,
         attention: presentation.attention,

package/packages/daemon/src/command-center/resources/fleet-catalog.ts

@@ -43,6 +43,7 @@ import {
   isAgentPane,
   resolveAgentPresentation,
   type ApplicationShellPanePresentationFacts,
+  resolvedAgentLabel,
 } from "./application-shell.ts";
 
 function digest(value: string): string {
@@ -123,16 +124,19 @@ function toPresentationPane(
   return {
     semanticPaneId: null,
     index,
-    title: "",
+    title: pane.title ?? "",
     currentCommand: pane.currentCommand,
     active: pane.active,
     role: null,
-    name: null,
+    name: pane.name ?? null,
+    nameSource: pane.nameSource,
     type: null,
     agentKind: pane.agentHintRaw,
     agentStateRaw: pane.agentStateRaw,
     agentStatusTextRaw: pane.agentStatusTextRaw,
     agentDisplayNameRaw: pane.agentDisplayNameRaw,
+    teamMemberName: pane.teamMemberName,
+    team: pane.team,
     // Authority-only: the fleet never scrapes an unopened session. `null` (not
     // `undefined`) keeps `resolveAgentPresentation` on the ground-truth path
     // while its scrape verdict resolves to `unknown` without any capture.
@@ -155,8 +159,12 @@ function projectSession(
     const presentation = resolveAgentPresentation(presentationPane, nowSec);
     agents.push({
       agentId: fleetAgentIdForPane(session.name, pane),
-      name: fleetLabel(presentation.displayName ?? pane.currentCommand, `Agent ${index + 1}`),
+      name: fleetLabel(
+        resolvedAgentLabel(presentationPane, presentation, index),
+        `Agent ${index + 1}`,
+      ),
       harness: harnessForPane(presentationPane),
+      ...(pane.team ? { team: pane.team } : {}),
       activity: presentation.activity,
       attention: presentation.attention,
       statusSource: presentation.statusSource,

package/packages/daemon/src/command-center/resources/fleet-resource-route.ts

@@ -14,7 +14,9 @@ export interface FleetResourceRouteOptions {
   /** Source of truth for which sessions the app created (`appCreated`). */
   readonly registry: Pick<WorkspaceRegistry, "list">;
   /** Daemon-generation-pinned tmux fleet read. Defaults only for legacy/test callers. */
-  readonly readFleet?: () => ReturnType<typeof readAdoptedFleet>;
+  readonly readFleet?: () =>
+    | ReturnType<typeof readAdoptedFleet>
+    | Promise<ReturnType<typeof readAdoptedFleet>>;
 }
 
 /**
@@ -36,7 +38,7 @@ export function mountFleetResourceRoute(app: Hono, options: FleetResourceRouteOp
     mismatchMessage: "Fleet catalog access requires owner authority",
   });
 
-  app.get("/api/resources/fleet-catalog", (c) => {
+  app.get("/api/resources/fleet-catalog", async (c) => {
     const gate = authorize(c);
     if (gate) return gate;
 
@@ -45,7 +47,7 @@ export function mountFleetResourceRoute(app: Hono, options: FleetResourceRouteOp
     // with a successful empty snapshot. Never expose raw socket/process errors.
     let sessions: ReturnType<typeof readAdoptedFleet>;
     try {
-      sessions = options.readFleet ? options.readFleet() : readAdoptedFleet(options.registry);
+      sessions = options.readFleet ? await options.readFleet() : readAdoptedFleet(options.registry);
     } catch {
       sessions = null;
     }

package/packages/daemon/src/command-center/server.ts

@@ -219,7 +219,7 @@ export interface CreateAppOptions {
     readonly paneCount: number;
   }[];
   /** Injectable daemon-generation-pinned adopted fleet projection. */
-  catalogFleet?: () => FleetSessionFacts[] | null;
+  catalogFleet?: () => FleetSessionFacts[] | null | Promise<FleetSessionFacts[] | null>;
   fleetPreviewCapture?: (
     liveSessionId: string,
     signal?: AbortSignal,

package/packages/daemon/src/lib/daemon-embed.ts

@@ -1,3 +1,5 @@
+import { join } from "node:path";
+import { createClaudeTeamMembershipReader } from "../terminal/attachments/claude-team-names.ts";
 import { PaneSourceDiscovery } from "./pane-source-discovery.ts";
 import { createBackgroundNativeCapture } from "./background-native-capture.ts";
 import { createOwnedViewerAdapterFactory } from "./owned-viewer-factory.ts";
@@ -842,7 +844,9 @@ async function startHttpServer({
     readonly sessionName: string;
     readonly paneCount: number;
   }[];
-  catalogFleet: () => ReturnType<typeof readAdoptedFleet>;
+  catalogFleet: () =>
+    | ReturnType<typeof readAdoptedFleet>
+    | Promise<ReturnType<typeof readAdoptedFleet>>;
   fleetPreviewCapture: (
     liveSessionId: string,
     signal?: AbortSignal,
@@ -1127,6 +1131,9 @@ async function startEmbeddedDaemonGeneration(
     // observe one daemon-generation authority rather than whichever server a
     // caller's ambient TMUX/PATH happens to select.
     const tmuxAuthority = resolveWorkspacePaneTmuxAuthority();
+    const readTeamMemberships = createClaudeTeamMembershipReader(
+      join(resolveRuntimeNamespace().claudeDir, "teams"),
+    );
     const catalogTmuxRunner = createPinnedWorkspaceTmuxRunner(tmuxAuthority);
     const initialTmuxProof = captureTmuxServerProof(catalogTmuxRunner);
     const initialNativeIdentityParts = initialTmuxProof
@@ -1621,6 +1628,7 @@ async function startEmbeddedDaemonGeneration(
         agentStatusProbeFactory: ({ run }) =>
           createTmuxAgentStatusProbe({
             run,
+            readTeamMemberships,
             captureNative: (pane, signal) =>
               backgroundCapture?.(
                 {
@@ -1900,8 +1908,8 @@ async function startEmbeddedDaemonGeneration(
         peekTerminalAttachmentRuntime,
         paneStreamRuntime,
         catalogLiveSessions: () => discoverLiveSessionSummaries(catalogTmuxRunner),
-        catalogFleet: () =>
-          readAdoptedFleet(
+        catalogFleet: async () => {
+          const fleet = readAdoptedFleet(
             workspaceRegistry,
             nativeGenerationTmuxRunner,
             (sessionName, pane) =>
@@ -1913,7 +1921,26 @@ async function startEmbeddedDaemonGeneration(
                   ) ?? null)
                 : null,
             () => observationSelector?.nativeServerEpoch ?? null,
-          ),
+          );
+          if (!fleet) return null;
+          const names = await readTeamMemberships(
+            fleet.flatMap((session) =>
+              session.panes.map((pane) => ({
+                runtimePaneId: pane.runtimePaneId,
+                pid: pane.incarnation,
+              })),
+            ),
+          );
+          return fleet.map((session) => ({
+            ...session,
+            panes: session.panes.map((pane) => {
+              const name = names.get(pane.runtimePaneId);
+              return name
+                ? { ...pane, teamMemberName: name.name, team: pane.team ?? name.team }
+                : pane;
+            }),
+          }));
+        },
         fleetPreviewCapture: createFleetPreviewCapture(fleetFactsTmuxRunner, {
           serverEpoch: () => observationSelector?.nativeServerEpoch ?? null,
           capture: (request, signal) =>

package/packages/daemon/src/pane-team.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { runtimeTmuxArgs } from "./lib/runtime-namespace.ts";
+import { manualPaneTeamStamp, PANE_TEAM_OPTION } from "./terminal/attachments/manual-pane-team.ts";
+
+/** Explicit membership only. Never launches, stops, or messages an agent. */
+export function assignPaneTeam(
+  options: {
+    paneId: string;
+    name: string | null;
+    socketPath?: string;
+    socketName?: string;
+  },
+  run: (args: string[]) => string = (args) =>
+    execFileSync("tmux", args, { encoding: "utf8", timeout: 5000 }),
+) {
+  if (!/^%\d+$/u.test(options.paneId)) throw new Error("Use an exact pane ID such as %3");
+  if (options.socketPath && options.socketName) throw new Error("Choose one tmux socket selector");
+  if (options.socketPath && !isAbsolute(options.socketPath))
+    throw new Error("Socket path must be absolute");
+  if (options.socketName && !/^[a-zA-Z0-9_.-]+$/u.test(options.socketName))
+    throw new Error("Invalid socket name");
+  const args = (command: string[]) =>
+    options.socketPath
+      ? ["-S", options.socketPath, ...command]
+      : options.socketName
+        ? ["-L", options.socketName, ...command]
+        : runtimeTmuxArgs(command);
+  const pid = Number(
+    run(args(["display-message", "-p", "-t", options.paneId, "#{pane_pid}"])).trim(),
+  );
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Error("Pane is no longer available");
+  const stamp = options.name === null ? null : manualPaneTeamStamp(options.name, pid);
+  run(
+    args(
+      stamp === null
+        ? ["set-option", "-p", "-u", "-t", options.paneId, PANE_TEAM_OPTION]
+        : ["set-option", "-p", "-t", options.paneId, PANE_TEAM_OPTION, stamp],
+    ),
+  );
+  return { paneId: options.paneId, team: options.name, source: stamp === null ? null : "manual" };
+}

package/packages/daemon/src/terminal/attachments/agent-status-probe.ts

@@ -1,3 +1,7 @@
+import { readManualPaneTeam } from "./manual-pane-team.ts";
+import type { PaneTeamMembership } from "@tmux-ide/contracts";
+import type { ClaudeTeamMembershipReader } from "./claude-team-names.ts";
+import type { ClaudeTeamNameReader } from "./claude-team-names.ts";
 import type { NativePaneIdentity } from "@tmux-ide/contracts";
 /**
  * Agent-status probe for the application-shell inventory — the IO half of the
@@ -42,6 +46,8 @@ import {
 
 /** The per-pane facts the pure projector consumes (see `ApplicationShellPanePresentationFacts`). */
 export interface AgentStatusPaneFacts {
+  readonly teamMemberName?: string;
+  readonly team?: PaneTeamMembership;
   /** Stable manifest id resolved from the pane hint, command, or process tree. */
   readonly agentKind: string | null;
   /** Raw `@agent_state` (`"<state>:<epoch>"`), or null when unset. */
@@ -93,6 +99,7 @@ const AGENT_OPTIONS_FORMAT = [
   "#{@agent_display_name}",
   "#{@agent_hint}",
   "#{pane_pid}",
+  "#{@tmux_ide_team}",
   AGENT_LINE_SENTINEL,
 ].join(AGENT_FIELD_SEPARATOR);
 
@@ -117,6 +124,7 @@ export const SCRAPE_CAPTURE_BUDGET = 4;
 const SCRAPE_CACHE_MAX_ENTRIES = 1024;
 
 interface RawPaneOptions {
+  readonly team?: PaneTeamMembership;
   readonly stateRaw: string | null;
   readonly statusTextRaw: string | null;
   readonly displayNameRaw: string | null;
@@ -151,12 +159,13 @@ function parseAgentOptions(stdout: string): ReadonlyMap<string, RawPaneOptions>
     if (line.length === 0) continue;
     const fields = line.split(AGENT_FIELD_SEPARATOR);
     // paneId, state, statusText, displayName, hint, pid, sentinel
-    if (fields.length !== 7 || fields[6] !== AGENT_LINE_SENTINEL) continue;
+    if (![7, 8].includes(fields.length) || fields.at(-1) !== AGENT_LINE_SENTINEL) continue;
     const runtimePaneId = fields[0]!;
     if (!RUNTIME_PANE_ID.test(runtimePaneId)) continue;
     const pidText = fields[5]!;
     const pid = /^[0-9]+$/u.test(pidText) ? Number(pidText) : null;
     result.set(runtimePaneId, {
+      team: fields.length === 8 ? readManualPaneTeam(fields[6], pid) : undefined,
       stateRaw: emptyToNull(fields[1]!),
       statusTextRaw: emptyToNull(fields[2]!),
       displayNameRaw: emptyToNull(fields[3]!),
@@ -168,6 +177,8 @@ function parseAgentOptions(stdout: string): ReadonlyMap<string, RawPaneOptions>
 }
 
 export interface TmuxAgentStatusProbeDeps {
+  readonly readTeamNames?: ClaudeTeamNameReader;
+  readonly readTeamMemberships?: ClaudeTeamMembershipReader;
   /** null proves no native dispatch; failures must never retry through stock capture. */
   readonly captureNative?: (
     pane: AgentStatusProbePane,
@@ -302,6 +313,7 @@ export function createTmuxAgentStatusProbe(deps: TmuxAgentStatusProbeDeps): Agen
       agentKind: string | null,
     ): void => {
       facts.set(pane.runtimePaneId, {
+        ...(raw?.team ? { team: raw.team } : {}),
         agentKind,
         agentStateRaw: raw?.stateRaw ?? null,
         agentStatusTextRaw: raw?.statusTextRaw ?? null,
@@ -429,6 +441,39 @@ export function createTmuxAgentStatusProbe(deps: TmuxAgentStatusProbeDeps): Agen
       emit(pane, raw, verdict, manifest.id);
     }
 
+    if (deps.readTeamMemberships) {
+      const memberships = await deps.readTeamMemberships(
+        input.panes.flatMap((pane) => {
+          const pid = options.get(pane.runtimePaneId)?.pid;
+          return pid ? [{ runtimePaneId: pane.runtimePaneId, pid }] : [];
+        }),
+      );
+      throwIfAborted(signal);
+      for (const [paneId, member] of memberships) {
+        const fact = facts.get(paneId);
+        if (fact)
+          facts.set(paneId, {
+            ...fact,
+            teamMemberName: member.name,
+            team: fact.team ?? member.team,
+          });
+      }
+    }
+
+    if (deps.readTeamNames) {
+      const names = await deps.readTeamNames(
+        input.panes.flatMap((pane) => {
+          const pid = options.get(pane.runtimePaneId)?.pid;
+          return pid ? [{ runtimePaneId: pane.runtimePaneId, pid }] : [];
+        }),
+      );
+      throwIfAborted(signal);
+      for (const [paneId, name] of names) {
+        const fact = facts.get(paneId);
+        if (fact) facts.set(paneId, { ...fact, teamMemberName: name });
+      }
+    }
+
     // Bound the cache: pane ids are server-unique and never re-probed after a
     // pane dies, so evict the oldest verdicts past the ceiling.
     if (stagedVerdicts.size > SCRAPE_CACHE_MAX_ENTRIES) {

package/packages/daemon/src/terminal/attachments/claude-team-names.ts

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import type { PaneTeamMembership } from "@tmux-ide/contracts";
+/** Read-only compatibility adapter for Claude Code's runtime team metadata.
+ * Names are presentation evidence, never agent identity or permission authority.
+ */
+import { open, readdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import {
+  readProcessTableAsync,
+  subtreeEntries,
+  type ProcEntry,
+} from "../../tui/detect/process-tree.ts";
+
+export interface ClaudeTeamMember {
+  readonly team: string;
+  readonly name: string;
+  readonly agentId: string;
+  readonly paneId: string;
+}
+export interface TeamPaneProcess {
+  readonly runtimePaneId: string;
+  readonly pid: number;
+}
+const token = (value: unknown): value is string =>
+  typeof value === "string" &&
+  /^[a-zA-Z0-9_.@-]{1,160}$/u.test(value) &&
+  value !== "." &&
+  value !== "..";
+
+export function parseClaudeTeamMembers(value: unknown, directory: string): ClaudeTeamMember[] {
+  if (!value || typeof value !== "object") return [];
+  const config = value as Record<string, unknown>;
+  if (
+    !token(directory) ||
+    config.name !== directory ||
+    !Array.isArray(config.members) ||
+    config.members.length > 128
+  )
+    return [];
+  return config.members.flatMap((value): ClaudeTeamMember[] => {
+    if (!value || typeof value !== "object") return [];
+    const m = value as Record<string, unknown>;
+    if (
+      !token(m.name) ||
+      m.name.length > 80 ||
+      !token(m.agentId) ||
+      m.backendType !== "tmux" ||
+      typeof m.tmuxPaneId !== "string" ||
+      !/^%\d+$/u.test(m.tmuxPaneId)
+    )
+      return [];
+    return [{ team: directory, name: m.name, agentId: m.agentId, paneId: m.tmuxPaneId }];
+  });
+}
+
+/** Conservative argv recognition: flattened ps text is not a shell parser.
+ * Ambiguous/quoted arguments fall back to the native title rather than guessing.
+ */
+function matchesProcess(command: string, member: ClaudeTeamMember): boolean {
+  const args = command.trim().split(/\s+/u);
+  const executable = args.shift() ?? "";
+  if (basename(executable) !== "claude" && !/\/claude\/versions\/\d[\w.-]*$/u.test(executable))
+    return false;
+  for (const [flag, expected] of [
+    ["--team-name", member.team],
+    ["--agent-id", member.agentId],
+    ["--agent-name", member.name],
+  ]) {
+    const positions = args.flatMap((arg, index) =>
+      arg === flag || arg.startsWith(`${flag}=`) ? [index] : [],
+    );
+    if (positions.length !== 1) return false;
+    const i = positions[0]!;
+    if ((args[i] === flag ? args[i + 1] : args[i]!.slice(flag!.length + 1)) !== expected)
+      return false;
+  }
+  return true;
+}
+
+export function resolveClaudeTeamMember(
+  pane: TeamPaneProcess,
+  members: readonly ClaudeTeamMember[],
+  processes: ProcEntry[],
+): ClaudeTeamMember | null {
+  // A native pane id alone cannot bind a team: different servers reuse %N.
+  // Its live shell PID scopes the match to this host and this pane's subtree.
+  const subtree = subtreeEntries(processes, pane.pid);
+  const matches = members.filter(
+    (m) => m.paneId === pane.runtimePaneId && subtree.some((p) => matchesProcess(p.command, m)),
+  );
+  return matches.length === 1 ? matches[0]! : null;
+}
+
+export function resolveClaudeTeamName(
+  pane: TeamPaneProcess,
+  members: readonly ClaudeTeamMember[],
+  processes: ProcEntry[],
+): string | null {
+  return resolveClaudeTeamMember(pane, members, processes)?.name ?? null;
+}
+
+export interface ClaudePaneTeam {
+  readonly name: string;
+  readonly team: PaneTeamMembership;
+}
+export type ClaudeTeamMembershipReader = (
+  panes: readonly TeamPaneProcess[],
+) => Promise<ReadonlyMap<string, ClaudePaneTeam>>;
+
+async function readMembers(directory: string): Promise<ClaudeTeamMember[]> {
+  try {
+    const entries = await readdir(directory, { withFileTypes: true });
+    if (entries.length > 128) return [];
+    const members: ClaudeTeamMember[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !token(entry.name)) continue;
+      try {
+        const file = await open(join(directory, entry.name, "config.json"), "r");
+        try {
+          if (!(await file.stat()).isFile()) continue;
+          const bytes = Buffer.alloc(256 * 1024 + 1);
+          const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+          if (bytesRead > 256 * 1024) continue;
+          members.push(
+            ...parseClaudeTeamMembers(
+              JSON.parse(bytes.subarray(0, bytesRead).toString("utf8")),
+              entry.name,
+            ),
+          );
+        } finally {
+          await file.close();
+        }
+      } catch {
+        /* Removal, atomic replacement and unknown schemas clear old facts. */
+      }
+    }
+    return members;
+  } catch {
+    return [];
+  }
+}
+
+export type ClaudeTeamNameReader = (
+  panes: readonly TeamPaneProcess[],
+) => Promise<ReadonlyMap<string, string>>;
+
+export function createClaudeTeamMembershipReader(
+  directory: string,
+  deps: {
+    readMembers?: () => Promise<ClaudeTeamMember[]>;
+    readProcesses?: () => Promise<ProcEntry[]>;
+    now?: () => number;
+  } = {},
+): ClaudeTeamMembershipReader {
+  const now = deps.now ?? Date.now;
+  let snapshot: { at: number; members: ClaudeTeamMember[]; processes: ProcEntry[] } | null = null;
+  let pending: Promise<void> | null = null;
+  return async (panes) => {
+    if (!panes.length) return new Map();
+    if (!snapshot || now() - snapshot.at >= 2000) {
+      pending ??= (async () => {
+        try {
+          const members = await (deps.readMembers?.() ?? readMembers(directory));
+          const processes = members.length
+            ? await (deps.readProcesses?.() ?? readProcessTableAsync())
+            : [];
+          snapshot = { at: now(), members, processes };
+        } catch {
+          snapshot = { at: now(), members: [], processes: [] };
+        }
+      })().finally(() => {
+        pending = null;
+      });
+      await pending;
+    }
+    const current = snapshot!;
+    const names = new Map<string, ClaudePaneTeam>();
+    for (const pane of panes) {
+      const member = resolveClaudeTeamMember(pane, current.members, current.processes);
+      if (member)
+        names.set(pane.runtimePaneId, {
+          name: member.name,
+          team: {
+            id: `team.${createHash("sha256").update(member.team).digest("hex").slice(0, 32)}`,
+            name: member.team.slice(0, 80),
+            source: "claude-code",
+          },
+        });
+    }
+    return names;
+  };
+}
+
+/** Compatibility API for callers interested only in the shared display name. */
+export function createClaudeTeamNameReader(
+  directory: string,
+  deps: Parameters<typeof createClaudeTeamMembershipReader>[1] = {},
+): ClaudeTeamNameReader {
+  const read = createClaudeTeamMembershipReader(directory, deps);
+  return async (panes) => new Map([...(await read(panes))].map(([id, value]) => [id, value.name]));
+}

package/packages/daemon/src/terminal/attachments/manual-pane-team.ts

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { PaneTeamMembershipSchemaZ, type PaneTeamMembership } from "@tmux-ide/contracts";
+
+export const PANE_TEAM_OPTION = "@tmux_ide_team";
+
+/** Pane-local metadata survives layout moves, but never a replacement process. */
+export function manualPaneTeamStamp(name: string, pid: number): string {
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Error("Invalid pane process");
+  const team = PaneTeamMembershipSchemaZ.parse({
+    id: `team.${createHash("sha256").update(name).digest("hex").slice(0, 32)}`,
+    name,
+    source: "manual",
+  });
+  return `v1.${Buffer.from(JSON.stringify({ version: 1, pid, team })).toString("base64url")}`;
+}
+
+export function readManualPaneTeam(
+  raw: string | null | undefined,
+  pid: number | null,
+): PaneTeamMembership | undefined {
+  if (!raw || raw.length > 2048 || !pid) return undefined;
+  try {
+    if (!/^v1\.[A-Za-z0-9_-]+$/u.test(raw)) return undefined;
+    const value = JSON.parse(Buffer.from(raw.slice(3), "base64url").toString("utf8"));
+    if (value.version !== 1 || value.pid !== pid) return undefined;
+    const parsed = PaneTeamMembershipSchemaZ.safeParse(value.team);
+    return parsed.success && parsed.data.source === "manual" ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/packages/daemon/src/terminal/attachments/native-runtime.ts

@@ -487,6 +487,7 @@ export interface NativeTerminalInventoryPaneSnapshot extends TrustedSemanticPane
   readonly active: boolean;
   readonly role: string | null;
   readonly name: string | null;
+  readonly nameSource?: string | null;
   readonly type: string | null;
   /** Durable `@tmux_ide_mission` creation stamp, or null when unset. */
   readonly missionStamp: string | null;
@@ -589,6 +590,7 @@ function projectTrustedMirrorInventory(
       active: pane.active,
       role: nullable(pane.role),
       name: nullable(pane.name),
+      ...(pane.nameSource ? { nameSource: nullable(pane.nameSource) } : {}),
       type: nullable(pane.type),
       missionStamp: nullable(pane.missionStamp),
       dir: boundedWireValue(pane.dir, 4_096),

package/packages/daemon/src/terminal/mirror/session-channel.ts

@@ -3530,6 +3530,7 @@ export class SessionChannel {
         active: descriptor.paneActive && descriptor.windowActive,
         role: descriptor.role,
         name: descriptor.name,
+        ...(descriptor.nameSource ? { nameSource: descriptor.nameSource } : {}),
         type: descriptor.type,
         missionStamp: descriptor.missionStamp,
         nativePaneBirthId: descriptor.nativePaneBirthId ?? null,

package/packages/daemon/src/terminal/mirror/trusted-inventory.ts

@@ -18,6 +18,7 @@ export interface TrustedMirrorPaneInventory {
   readonly active: boolean;
   readonly role: string | null;
   readonly name: string | null;
+  readonly nameSource?: string | null;
   readonly type: string | null;
   readonly missionStamp: string | null;
   readonly dir: string;