tmux-team 4.0.0 → 4.1.0

package/src/tmux.test.ts

@@ -3,15 +3,17 @@
 // ─────────────────────────────────────────────────────────────
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import { createTmux } from './tmux.js';
 
 // Mock child_process
 vi.mock('child_process', () => ({
   execSync: vi.fn(),
+  execFileSync: vi.fn(),
 }));
 
 const mockedExecSync = vi.mocked(execSync);
+const mockedExecFileSync = vi.mocked(execFileSync);
 
 describe('createTmux', () => {
   beforeEach(() => {
@@ -192,6 +194,56 @@ describe('createTmux', () => {
         { id: '%2', command: 'codex', suggestedName: 'codex' },
       ]);
     });
+
+    it('ignores invalid metadata and duplicate pane IDs', () => {
+      mockedExecSync.mockReturnValue('%1\tcodex\tbad-json\n%1\tcodex\tbad-json\n%2\tzsh\t{}\n');
+      const tmux = createTmux();
+      expect(tmux.listPanes()).toEqual([
+        { id: '%1', command: 'codex', suggestedName: 'codex' },
+        { id: '%2', command: 'zsh', suggestedName: null },
+      ]);
+      expect(tmux.getAgentRegistry({ type: 'workspace', workspaceRoot: '/repo' })).toEqual({
+        paneRegistry: {},
+        agents: {},
+      });
+    });
+
+    it('parses tmux-team pane metadata', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"workspaces":{"/repo":{"name":"codex","remark":"review"}}}\n'
+      );
+      const tmux = createTmux();
+      expect(tmux.getAgentRegistry({ type: 'workspace', workspaceRoot: '/repo' })).toEqual({
+        paneRegistry: { codex: { pane: '%1', remark: 'review' } },
+        agents: {},
+      });
+    });
+
+    it('parses pane target and cwd from modern list-panes output', () => {
+      mockedExecSync.mockReturnValue('%1\tmain:2.0\t/repo\tcodex\t{"version":1}\n');
+      const tmux = createTmux();
+      expect(tmux.listPanes()).toEqual([
+        {
+          id: '%1',
+          target: 'main:2.0',
+          cwd: '/repo',
+          command: 'codex',
+          suggestedName: 'codex',
+          metadata: { version: 1 },
+        },
+      ]);
+    });
+
+    it('builds team registries and agent config from metadata', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"teams":{"egp":{"name":"codex","preamble":"Be strict","deny":["x"]}}}\n'
+      );
+      const tmux = createTmux();
+      expect(tmux.getAgentRegistry({ type: 'team', teamName: 'egp' })).toEqual({
+        paneRegistry: { codex: { pane: '%1', preamble: 'Be strict', deny: ['x'] } },
+        agents: { codex: { preamble: 'Be strict', deny: ['x'] } },
+      });
+    });
   });
 
   describe('getCurrentPaneId', () => {
@@ -233,6 +285,143 @@ describe('createTmux', () => {
     });
   });
 
+  describe('metadata registry writes', () => {
+    it('resolves pane targets to canonical pane IDs', () => {
+      mockedExecFileSync.mockReturnValue('%9\n');
+      const tmux = createTmux();
+      expect(tmux.resolvePaneTarget('1.2')).toBe('%9');
+      expect(mockedExecFileSync).toHaveBeenCalledWith(
+        'tmux',
+        ['display-message', '-p', '-t', '1.2', '#{pane_id}'],
+        expect.any(Object)
+      );
+    });
+
+    it('sets workspace registration on pane metadata', () => {
+      mockedExecFileSync.mockReturnValueOnce('');
+      const tmux = createTmux();
+      tmux.setAgentRegistration(
+        '%9',
+        { type: 'workspace', workspaceRoot: '/repo' },
+        { name: 'codex', preamble: 'Be strict' }
+      );
+      expect(mockedExecFileSync).toHaveBeenLastCalledWith(
+        'tmux',
+        [
+          'set-option',
+          '-p',
+          '-t',
+          '%9',
+          '@tmux-team.agent',
+          '{"version":1,"workspaces":{"/repo":{"name":"codex","preamble":"Be strict"}}}',
+        ],
+        expect.any(Object)
+      );
+    });
+
+    it('sets team registration while preserving existing metadata', () => {
+      mockedExecFileSync.mockReturnValueOnce(
+        '{"version":1,"workspaces":{"/repo":{"name":"codex"}}}\n'
+      );
+      const tmux = createTmux();
+      tmux.setAgentRegistration('%9', { type: 'team', teamName: 'egp' }, { name: 'reviewer' });
+      expect(mockedExecFileSync).toHaveBeenLastCalledWith(
+        'tmux',
+        [
+          'set-option',
+          '-p',
+          '-t',
+          '%9',
+          '@tmux-team.agent',
+          '{"version":1,"workspaces":{"/repo":{"name":"codex"}},"teams":{"egp":{"name":"reviewer"}}}',
+        ],
+        expect.any(Object)
+      );
+    });
+
+    it('clears scoped registration and unsets empty metadata', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"workspaces":{"/repo":{"name":"codex"}}}\n'
+      );
+      const tmux = createTmux();
+      expect(
+        tmux.clearAgentRegistration('codex', { type: 'workspace', workspaceRoot: '/repo' })
+      ).toBe(true);
+      expect(mockedExecFileSync).toHaveBeenCalledWith(
+        'tmux',
+        ['set-option', '-p', '-u', '-t', '%1', '@tmux-team.agent'],
+        expect.any(Object)
+      );
+    });
+
+    it('returns false when clearing a missing registration', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"workspaces":{"/repo":{"name":"codex"}}}\n'
+      );
+      const tmux = createTmux();
+      expect(
+        tmux.clearAgentRegistration('claude', { type: 'workspace', workspaceRoot: '/repo' })
+      ).toBe(false);
+      expect(mockedExecFileSync).not.toHaveBeenCalled();
+    });
+
+    it('lists teams from pane metadata', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"teams":{"egp":{"name":"codex"},"checkout":{"name":"claude"}}}\n'
+      );
+      const tmux = createTmux();
+      expect(tmux.listTeams()).toEqual({ checkout: ['claude'], egp: ['codex'] });
+    });
+
+    it('lists pane team and workspace details', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tmain:1.0\t/repo\tclaude\t{"version":1,"workspaces":{"/repo":{"name":"claude","remark":"lead"}},"teams":{"egp":{"name":"reviewer"}}}\n%2\tmain:1.1\t/tmp\tzsh\t\n'
+      );
+      const tmux = createTmux();
+      expect(tmux.listTeamPanes()).toEqual([
+        {
+          pane: '%1',
+          target: 'main:1.0',
+          cwd: '/repo',
+          command: 'claude',
+          suggestedName: 'claude',
+          registrations: [
+            { scopeType: 'team', scope: 'egp', agent: 'reviewer' },
+            { scopeType: 'workspace', scope: '/repo', agent: 'claude', remark: 'lead' },
+          ],
+        },
+        {
+          pane: '%2',
+          target: 'main:1.1',
+          cwd: '/tmp',
+          command: 'zsh',
+          suggestedName: null,
+          registrations: [],
+        },
+      ]);
+    });
+
+    it('removes one team while preserving other registrations', () => {
+      mockedExecSync.mockReturnValue(
+        '%1\tcodex\t{"version":1,"teams":{"egp":{"name":"codex"},"checkout":{"name":"claude"}}}\n'
+      );
+      const tmux = createTmux();
+      expect(tmux.removeTeam('egp')).toEqual({ removed: 1, agents: ['codex'] });
+      expect(mockedExecFileSync).toHaveBeenCalledWith(
+        'tmux',
+        [
+          'set-option',
+          '-p',
+          '-t',
+          '%1',
+          '@tmux-team.agent',
+          '{"version":1,"teams":{"checkout":{"name":"claude"}}}',
+        ],
+        expect.any(Object)
+      );
+    });
+  });
+
   describe('pane ID handling', () => {
     it('accepts window.pane format', () => {
       mockedExecSync.mockReturnValue('');

package/src/tmux.ts

@@ -2,9 +2,19 @@
 // Pure tmux wrapper - buffer paste, capture-pane, pane detection
 // ─────────────────────────────────────────────────────────────
 
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import crypto from 'crypto';
-import type { Tmux, PaneInfo } from './types.js';
+import type {
+  AgentRegistration,
+  PaneAgentMetadata,
+  Tmux,
+  PaneInfo,
+  RegistryScope,
+  TeamPaneInfo,
+  TmuxRegistry,
+} from './types.js';
+
+const AGENT_METADATA_OPTION = '@tmux-team.agent';
 
 // Known agent patterns for auto-detection
 const KNOWN_AGENTS: Record<string, string[]> = {
@@ -27,6 +37,151 @@ function detectAgentName(command: string): string | null {
   return null;
 }
 
+function safeParseMetadata(text: string): PaneAgentMetadata | undefined {
+  if (!text.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(text) as PaneAgentMetadata;
+    if (!parsed || parsed.version !== 1 || typeof parsed !== 'object') {
+      return undefined;
+    }
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function emptyMetadata(): PaneAgentMetadata {
+  return { version: 1 };
+}
+
+function registrationForScope(
+  metadata: PaneAgentMetadata | undefined,
+  scope: RegistryScope
+): AgentRegistration | undefined {
+  if (!metadata) return undefined;
+  if (scope.type === 'team') {
+    return metadata.teams?.[scope.teamName];
+  }
+  return metadata.workspaces?.[scope.workspaceRoot];
+}
+
+function setRegistrationForScope(
+  metadata: PaneAgentMetadata,
+  scope: RegistryScope,
+  registration: AgentRegistration
+): PaneAgentMetadata {
+  if (scope.type === 'team') {
+    metadata.teams = { ...metadata.teams, [scope.teamName]: registration };
+  } else {
+    metadata.workspaces = {
+      ...metadata.workspaces,
+      [scope.workspaceRoot]: registration,
+    };
+  }
+  return metadata;
+}
+
+function deleteRegistrationForScope(
+  metadata: PaneAgentMetadata,
+  scope: RegistryScope
+): AgentRegistration | undefined {
+  let removed: AgentRegistration | undefined;
+  if (scope.type === 'team') {
+    removed = metadata.teams?.[scope.teamName];
+    if (metadata.teams) {
+      delete metadata.teams[scope.teamName];
+      if (Object.keys(metadata.teams).length === 0) delete metadata.teams;
+    }
+  } else {
+    removed = metadata.workspaces?.[scope.workspaceRoot];
+    if (metadata.workspaces) {
+      delete metadata.workspaces[scope.workspaceRoot];
+      if (Object.keys(metadata.workspaces).length === 0) delete metadata.workspaces;
+    }
+  }
+  return removed;
+}
+
+function hasRegistrations(metadata: PaneAgentMetadata): boolean {
+  return Boolean(
+    (metadata.workspaces && Object.keys(metadata.workspaces).length > 0) ||
+    (metadata.teams && Object.keys(metadata.teams).length > 0)
+  );
+}
+
+function registryFromPanes(panes: PaneInfo[], scope: RegistryScope): TmuxRegistry {
+  const paneRegistry: TmuxRegistry['paneRegistry'] = {};
+  const agents: TmuxRegistry['agents'] = {};
+
+  for (const pane of panes) {
+    const registration = registrationForScope(pane.metadata, scope);
+    if (!registration || paneRegistry[registration.name]) {
+      continue;
+    }
+
+    paneRegistry[registration.name] = {
+      pane: pane.id,
+      ...(registration.remark !== undefined && { remark: registration.remark }),
+      ...(registration.preamble !== undefined && { preamble: registration.preamble }),
+      ...(registration.deny !== undefined && { deny: registration.deny }),
+    };
+
+    if (
+      Object.prototype.hasOwnProperty.call(registration, 'preamble') ||
+      Object.prototype.hasOwnProperty.call(registration, 'deny')
+    ) {
+      agents[registration.name] = {
+        ...(Object.prototype.hasOwnProperty.call(registration, 'preamble') && {
+          preamble: registration.preamble,
+        }),
+        ...(Object.prototype.hasOwnProperty.call(registration, 'deny') && {
+          deny: registration.deny,
+        }),
+      };
+    }
+  }
+
+  return { paneRegistry, agents };
+}
+
+function teamPaneInfoFromPane(pane: PaneInfo): TeamPaneInfo {
+  const registrations: TeamPaneInfo['registrations'] = [];
+
+  for (const [workspaceRoot, registration] of Object.entries(pane.metadata?.workspaces ?? {})) {
+    registrations.push({
+      scopeType: 'workspace',
+      scope: workspaceRoot,
+      agent: registration.name,
+      ...(registration.remark !== undefined && { remark: registration.remark }),
+    });
+  }
+
+  for (const [teamName, registration] of Object.entries(pane.metadata?.teams ?? {})) {
+    registrations.push({
+      scopeType: 'team',
+      scope: teamName,
+      agent: registration.name,
+      ...(registration.remark !== undefined && { remark: registration.remark }),
+    });
+  }
+
+  registrations.sort(
+    (a, b) =>
+      a.scopeType.localeCompare(b.scopeType) ||
+      a.scope.localeCompare(b.scope) ||
+      a.agent.localeCompare(b.agent)
+  );
+
+  return {
+    pane: pane.id,
+    ...(pane.target && { target: pane.target }),
+    ...(pane.cwd && { cwd: pane.cwd }),
+    command: pane.command,
+    suggestedName: pane.suggestedName,
+    registrations,
+  };
+}
+
 export function createTmux(): Tmux {
   function sleepMs(ms: number): void {
     if (ms <= 0) return;
@@ -88,29 +243,57 @@ export function createTmux(): Tmux {
 
     listPanes(): PaneInfo[] {
       try {
-        // Get all panes with their IDs and current commands
-        const output = execSync('tmux list-panes -a -F "#{pane_id}\t#{pane_current_command}"', {
-          encoding: 'utf-8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-        });
+        // Get all panes with stable IDs, human tmux targets, cwd, commands, and tmux-team metadata.
+        const output = execSync(
+          `tmux list-panes -a -F "#{pane_id}\t#{session_name}:#{window_index}.#{pane_index}\t#{pane_current_path}\t#{pane_current_command}\t#{${AGENT_METADATA_OPTION}}"`,
+          {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }
+        );
 
+        const seen = new Set<string>();
         return output
-          .trim()
           .split('\n')
           .filter((line) => line.trim())
           .map((line) => {
-            const [id, command] = line.split('\t');
+            const fields = line.split('\t');
+            const [id, target, cwd, command, metadataText = ''] =
+              fields.length >= 5
+                ? fields
+                : [fields[0], undefined, undefined, fields[1] ?? '', fields[2] ?? ''];
+            const metadata = safeParseMetadata(metadataText);
             return {
               id: id || '',
+              ...(target && { target }),
+              ...(cwd && { cwd }),
               command: command || '',
               suggestedName: detectAgentName(command || ''),
+              ...(metadata && { metadata }),
             };
+          })
+          .filter((pane) => {
+            if (!pane.id || seen.has(pane.id)) return false;
+            seen.add(pane.id);
+            return true;
           });
       } catch {
         return [];
       }
     },
 
+    resolvePaneTarget(target: string): string | null {
+      try {
+        const output = execFileSync('tmux', ['display-message', '-p', '-t', target, '#{pane_id}'], {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return output.trim() || null;
+      } catch {
+        return null;
+      }
+    },
+
     getCurrentPaneId(): string | null {
       // First check environment variable
       if (process.env.TMUX_PANE) {
@@ -128,5 +311,102 @@ export function createTmux(): Tmux {
         return null;
       }
     },
+
+    getAgentRegistry(scope: RegistryScope): TmuxRegistry {
+      return registryFromPanes(this.listPanes(), scope);
+    },
+
+    setAgentRegistration(
+      paneId: string,
+      scope: RegistryScope,
+      registration: AgentRegistration
+    ): void {
+      const metadata = readPaneMetadata(paneId);
+      const next = setRegistrationForScope(metadata, scope, registration);
+      writePaneMetadata(paneId, next);
+    },
+
+    clearAgentRegistration(name: string, scope: RegistryScope): boolean {
+      let removed = false;
+      for (const pane of this.listPanes()) {
+        const registration = registrationForScope(pane.metadata, scope);
+        if (registration?.name !== name) continue;
+
+        const metadata = pane.metadata ?? emptyMetadata();
+        deleteRegistrationForScope(metadata, scope);
+        writePaneMetadata(pane.id, metadata);
+        removed = true;
+      }
+      return removed;
+    },
+
+    listTeams(): Record<string, string[]> {
+      const teams: Record<string, Set<string>> = {};
+      for (const pane of this.listPanes()) {
+        for (const [teamName, registration] of Object.entries(pane.metadata?.teams ?? {})) {
+          if (!teams[teamName]) teams[teamName] = new Set<string>();
+          teams[teamName].add(registration.name);
+        }
+      }
+      return Object.fromEntries(
+        Object.entries(teams).map(([teamName, agents]) => [teamName, [...agents].sort()])
+      );
+    },
+
+    listTeamPanes(): TeamPaneInfo[] {
+      return this.listPanes().map(teamPaneInfoFromPane);
+    },
+
+    removeTeam(teamName: string): { removed: number; agents: string[] } {
+      const agents = new Set<string>();
+      let removed = 0;
+      for (const pane of this.listPanes()) {
+        if (!pane.metadata?.teams?.[teamName]) continue;
+
+        agents.add(pane.metadata.teams[teamName].name);
+        const metadata = pane.metadata;
+        const teamRegistrations = metadata.teams;
+        if (teamRegistrations) {
+          delete teamRegistrations[teamName];
+          if (Object.keys(teamRegistrations).length === 0) delete metadata.teams;
+        }
+        writePaneMetadata(pane.id, metadata);
+        removed += 1;
+      }
+      return { removed, agents: [...agents].sort() };
+    },
   };
 }
+
+function readPaneMetadata(paneId: string): PaneAgentMetadata {
+  try {
+    const output = execFileSync(
+      'tmux',
+      ['show-options', '-p', '-t', paneId, '-v', AGENT_METADATA_OPTION],
+      {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+    return safeParseMetadata(output) ?? emptyMetadata();
+  } catch {
+    return emptyMetadata();
+  }
+}
+
+function writePaneMetadata(paneId: string, metadata: PaneAgentMetadata): void {
+  if (!hasRegistrations(metadata)) {
+    execFileSync('tmux', ['set-option', '-p', '-u', '-t', paneId, AGENT_METADATA_OPTION], {
+      stdio: 'pipe',
+    });
+    return;
+  }
+
+  execFileSync(
+    'tmux',
+    ['set-option', '-p', '-t', paneId, AGENT_METADATA_OPTION, JSON.stringify(metadata)],
+    {
+      stdio: 'pipe',
+    }
+  );
+}

package/src/types.ts

@@ -14,6 +14,24 @@ export interface PaneEntry {
   deny?: string[]; // Permission deny patterns
 }
 
+export interface AgentRegistration {
+  name: string;
+  remark?: string;
+  preamble?: string;
+  deny?: string[];
+}
+
+export interface PaneAgentMetadata {
+  version: 1;
+  workspaces?: Record<string, AgentRegistration>;
+  teams?: Record<string, AgentRegistration>;
+}
+
+export interface TmuxRegistry {
+  paneRegistry: Record<string, PaneEntry>;
+  agents: Record<string, AgentConfig>;
+}
+
 export interface ConfigDefaults {
   timeout: number; // seconds
   pollInterval: number; // seconds
@@ -51,6 +69,7 @@ export interface ResolvedConfig {
   defaults: ConfigDefaults;
   agents: Record<string, AgentConfig>;
   paneRegistry: Record<string, PaneEntry>;
+  registrySource?: 'tmux' | 'legacy' | 'none';
 }
 
 export interface Flags {
@@ -72,6 +91,7 @@ export interface Paths {
   globalConfig: string;
   localConfig: string;
   stateFile: string;
+  workspaceRoot?: string;
 }
 
 export interface UI {
@@ -85,8 +105,27 @@ export interface UI {
 
 export interface PaneInfo {
   id: string; // e.g., "%1"
+  target?: string; // e.g., "main:1.0"
+  cwd?: string; // pane_current_path
   command: string; // e.g., "node", "python", "zsh"
   suggestedName: string | null; // e.g., "codex" if detected from command
+  metadata?: PaneAgentMetadata;
+}
+
+export interface TeamPaneRegistration {
+  scopeType: 'workspace' | 'team';
+  scope: string;
+  agent: string;
+  remark?: string;
+}
+
+export interface TeamPaneInfo {
+  pane: string;
+  target?: string;
+  cwd?: string;
+  command: string;
+  suggestedName: string | null;
+  registrations: TeamPaneRegistration[];
 }
 
 export interface Tmux {
@@ -94,8 +133,23 @@ export interface Tmux {
   capture: (paneId: string, lines: number) => string;
   listPanes: () => PaneInfo[];
   getCurrentPaneId: () => string | null;
+  resolvePaneTarget: (target: string) => string | null;
+  getAgentRegistry: (scope: RegistryScope) => TmuxRegistry;
+  setAgentRegistration: (
+    paneId: string,
+    scope: RegistryScope,
+    registration: AgentRegistration
+  ) => void;
+  clearAgentRegistration: (name: string, scope: RegistryScope) => boolean;
+  listTeams: () => Record<string, string[]>;
+  listTeamPanes: () => TeamPaneInfo[];
+  removeTeam: (teamName: string) => { removed: number; agents: string[] };
 }
 
+export type RegistryScope =
+  | { type: 'workspace'; workspaceRoot: string }
+  | { type: 'team'; teamName: string };
+
 export interface WaitResult {
   requestId: string;
   nonce: string;
@@ -110,5 +164,6 @@ export interface Context {
   config: ResolvedConfig;
   tmux: Tmux;
   paths: Paths;
+  registryScope?: RegistryScope;
   exit: (code: number) => never;
 }

package/src/ui.test.ts

@@ -101,7 +101,13 @@ describe('ui', () => {
     const { createUI } = await import('./ui.js');
     const ui = createUI(false);
 
-    ui.table(['Name', 'Value'], [['test', ''], ['empty', null as unknown as string]]);
+    ui.table(
+      ['Name', 'Value'],
+      [
+        ['test', ''],
+        ['empty', null as unknown as string],
+      ]
+    );
     const output = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
     // Empty cells should be rendered as '-'
     expect(output).toContain('-');