tmux-team 4.0.0 → 4.1.0

package/src/commands/basic-commands.test.ts

@@ -17,6 +17,8 @@ import { cmdConfig } from './config.js';
 import { cmdCompletion } from './completion.js';
 import { cmdHelp } from './help.js';
 import { cmdLearn } from './learn.js';
+import { cmdMigrate } from './migrate.js';
+import { cmdTeam } from './team.js';
 
 function createMockUI(): UI & { jsonCalls: unknown[] } {
   return {
@@ -38,6 +40,13 @@ function createMockTmux(): Tmux {
     capture: vi.fn(() => 'captured'),
     listPanes: vi.fn(() => []),
     getCurrentPaneId: vi.fn(() => null),
+    resolvePaneTarget: vi.fn((target: string) => target),
+    getAgentRegistry: vi.fn(() => ({ paneRegistry: {}, agents: {} })),
+    setAgentRegistration: vi.fn(),
+    clearAgentRegistration: vi.fn(() => false),
+    listTeams: vi.fn(() => ({})),
+    listTeamPanes: vi.fn(() => []),
+    removeTeam: vi.fn(() => ({ removed: 0, agents: [] })),
   };
 }
 
@@ -54,7 +63,14 @@ function createCtx(
   const baseConfig: ResolvedConfig = {
     mode: 'polling',
     preambleMode: 'always',
-    defaults: { timeout: 180, pollInterval: 1, captureLines: 100, maxCaptureLines: 2000, preambleEvery: 3, pasteEnterDelayMs: 500 },
+    defaults: {
+      timeout: 180,
+      pollInterval: 1,
+      captureLines: 100,
+      maxCaptureLines: 2000,
+      preambleEvery: 3,
+      pasteEnterDelayMs: 500,
+    },
     agents: {},
     paneRegistry: {},
     ...overrides?.config,
@@ -107,12 +123,14 @@ describe('basic commands', () => {
     expect((ctx.ui as any).jsonCalls[0]).toMatchObject({ created: ctx.paths.localConfig });
   });
 
-  it('cmdAdd creates config if missing and writes new agent', () => {
+  it('cmdAdd writes new agent to tmux metadata', () => {
     const ctx = createCtx(testDir);
     cmdAdd(ctx, 'codex', '1.1', 'review');
-    const saved = JSON.parse(fs.readFileSync(ctx.paths.localConfig, 'utf-8'));
-    expect(saved.codex.pane).toBe('1.1');
-    expect(saved.codex.remark).toBe('review');
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '1.1',
+      expect.objectContaining({ type: 'workspace' }),
+      { name: 'codex', remark: 'review' }
+    );
   });
 
   it('cmdAdd errors if agent exists', () => {
@@ -125,9 +143,11 @@ describe('basic commands', () => {
     const ctx = createCtx(testDir);
     (ctx.tmux.getCurrentPaneId as ReturnType<typeof vi.fn>).mockReturnValue('%5');
     cmdThis(ctx, 'myagent', 'test remark');
-    const saved = JSON.parse(fs.readFileSync(ctx.paths.localConfig, 'utf-8'));
-    expect(saved.myagent.pane).toBe('%5');
-    expect(saved.myagent.remark).toBe('test remark');
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '%5',
+      expect.objectContaining({ type: 'workspace' }),
+      { name: 'myagent', remark: 'test remark' }
+    );
   });
 
   it('cmdThis errors when not in tmux', () => {
@@ -166,22 +186,32 @@ describe('basic commands', () => {
     });
     fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({ codex: { pane: '1.1' } }, null, 2));
     cmdRemove(ctx, 'codex');
-    expect((ctx.ui as any).jsonCalls).toEqual([{ removed: 'codex' }]);
+    expect((ctx.ui as any).jsonCalls).toEqual([{ removed: 'codex', source: 'legacy' }]);
   });
 
-  it('cmdUpdate updates pane and remark; creates entry if missing', () => {
+  it('cmdUpdate updates pane and remark in tmux metadata', () => {
     const ctx = createCtx(testDir, { config: { paneRegistry: { codex: { pane: '1.1' } } } });
     fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({}, null, 2));
     cmdUpdate(ctx, 'codex', { pane: '2.2', remark: 'new' });
-    const saved = JSON.parse(fs.readFileSync(ctx.paths.localConfig, 'utf-8'));
-    expect(saved.codex.pane).toBe('2.2');
-    expect(saved.codex.remark).toBe('new');
+    expect(ctx.tmux.clearAgentRegistration).toHaveBeenCalledWith(
+      'codex',
+      expect.objectContaining({ type: 'workspace' })
+    );
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '2.2',
+      expect.objectContaining({ type: 'workspace' }),
+      { name: 'codex', remark: 'new' }
+    );
   });
 
   it('cmdUpdate errors when agent not found', () => {
     const ctx = createCtx(testDir);
-    expect(() => cmdUpdate(ctx, 'notfound', { pane: '1.0' })).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
-    expect(ctx.ui.error).toHaveBeenCalledWith("Agent 'notfound' not found. Use 'tmux-team add' to create.");
+    expect(() => cmdUpdate(ctx, 'notfound', { pane: '1.0' })).toThrow(
+      `exit(${ExitCodes.PANE_NOT_FOUND})`
+    );
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      "Agent 'notfound' not found. Use 'tmux-team add' to create."
+    );
   });
 
   it('cmdUpdate errors when no updates specified', () => {
@@ -197,7 +227,9 @@ describe('basic commands', () => {
     });
     fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({ codex: { pane: '1.1' } }, null, 2));
     cmdUpdate(ctx, 'codex', { pane: '2.0', remark: 'updated' });
-    expect((ctx.ui as any).jsonCalls).toEqual([{ updated: 'codex', pane: '2.0', remark: 'updated' }]);
+    expect((ctx.ui as any).jsonCalls).toEqual([
+      { updated: 'codex', pane: '2.0', remark: 'updated' },
+    ]);
   });
 
   it('cmdList outputs JSON when --json', () => {
@@ -215,6 +247,14 @@ describe('basic commands', () => {
     expect(ctx.ui.info).toHaveBeenCalled();
   });
 
+  it('cmdList prints team hint when no shared team agents exist', () => {
+    const ctx = createCtx(testDir, { flags: { team: 'egp' } });
+    cmdList(ctx);
+    expect(ctx.ui.info).toHaveBeenCalledWith(
+      'No agents in team "egp". Use \'tmt this <name> --team egp\' to add one.'
+    );
+  });
+
   it('cmdList prints table when agents exist', () => {
     const ctx = createCtx(testDir, {
       config: { paneRegistry: { claude: { pane: '1.0', remark: 'main' } } },
@@ -223,6 +263,16 @@ describe('basic commands', () => {
     expect(ctx.ui.table).toHaveBeenCalled();
   });
 
+  it('cmdList warns when using legacy registry', () => {
+    const ctx = createCtx(testDir, {
+      config: { paneRegistry: { claude: { pane: '1.0' } }, registrySource: 'legacy' },
+    });
+    cmdList(ctx);
+    expect(ctx.ui.warn).toHaveBeenCalledWith(
+      'Using legacy tmux-team.json registry. Run `tmt migrate` to store registrations in tmux.'
+    );
+  });
+
   it('cmdList shows dash for missing remark', () => {
     const ctx = createCtx(testDir, {
       config: { paneRegistry: { claude: { pane: '1.0' } } }, // no remark
@@ -327,7 +377,9 @@ describe('basic commands', () => {
   it('cmdConfig set errors when not enough args', () => {
     const ctx = createCtx(testDir);
     expect(() => cmdConfig(ctx, ['set', 'mode'])).toThrow(`exit(${ExitCodes.ERROR})`);
-    expect(ctx.ui.error).toHaveBeenCalledWith('Usage: tmux-team config set <key> <value> [--global]');
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      'Usage: tmux-team config set <key> <value> [--global]'
+    );
   });
 
   it('cmdConfig errors on unknown subcommand', () => {
@@ -360,6 +412,230 @@ describe('basic commands', () => {
     );
   });
 
+  it('cmdMigrate dry-run reports legacy entries without writing tmux metadata', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    fs.writeFileSync(
+      ctx.paths.localConfig,
+      JSON.stringify({ claude: { pane: '1.1', remark: 'review' } }, null, 2)
+    );
+
+    cmdMigrate(ctx, ['--dry-run']);
+
+    expect(ctx.tmux.setAgentRegistration).not.toHaveBeenCalled();
+    expect((ctx.ui as any).jsonCalls[0]).toMatchObject({
+      dryRun: true,
+      migrated: 0,
+      items: [{ agent: 'claude', fromPane: '1.1', pane: '1.1', status: 'ready' }],
+    });
+  });
+
+  it('cmdMigrate writes tmux metadata and can clean legacy entries', () => {
+    const ctx = createCtx(testDir);
+    fs.writeFileSync(
+      ctx.paths.localConfig,
+      JSON.stringify({
+        $config: { mode: 'wait' },
+        claude: { pane: '1.1', remark: 'review', preamble: 'Be helpful' },
+      })
+    );
+
+    cmdMigrate(ctx, ['--cleanup']);
+
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '1.1',
+      expect.objectContaining({ type: 'workspace' }),
+      { name: 'claude', remark: 'review', preamble: 'Be helpful' }
+    );
+    const saved = JSON.parse(fs.readFileSync(ctx.paths.localConfig, 'utf-8'));
+    expect(saved.$config.mode).toBe('wait');
+    expect(saved.claude).toBeUndefined();
+  });
+
+  it('cmdMigrate errors when a legacy pane cannot be resolved', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue(null);
+    fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({ claude: { pane: 'missing' } }));
+
+    expect(() => cmdMigrate(ctx, [])).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
+  });
+
+  it('cmdMigrate reports when no legacy agents exist', () => {
+    const ctx = createCtx(testDir);
+    fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({ $config: { mode: 'wait' } }));
+
+    cmdMigrate(ctx, []);
+
+    expect(ctx.ui.info).toHaveBeenCalledWith(`No legacy agents found in ${ctx.paths.localConfig}`);
+  });
+
+  it('cmdTeam lists all pane team/workspace scopes', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
+      egp: ['claude', 'codex'],
+    });
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%1',
+        target: 'main:1.0',
+        cwd: '/repo',
+        command: 'claude',
+        suggestedName: 'claude',
+        registrations: [
+          { scopeType: 'workspace', scope: '/repo', agent: 'claude', remark: 'lead' },
+          { scopeType: 'team', scope: 'egp', agent: 'claude' },
+        ],
+      },
+    ]);
+
+    cmdTeam(ctx, ['ls']);
+
+    expect((ctx.ui as any).jsonCalls).toEqual([
+      {
+        teams: { egp: ['claude', 'codex'] },
+        panes: [
+          {
+            pane: '%1',
+            target: 'main:1.0',
+            cwd: '/repo',
+            command: 'claude',
+            suggestedName: 'claude',
+            registrations: [
+              { scopeType: 'workspace', scope: '/repo', agent: 'claude', remark: 'lead' },
+              { scopeType: 'team', scope: 'egp', agent: 'claude' },
+            ],
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('cmdTeam shows empty state and errors on unknown subcommands', () => {
+    const ctx = createCtx(testDir);
+
+    cmdTeam(ctx, ['ls']);
+    expect(ctx.ui.info).toHaveBeenCalledWith('No tmux panes found.');
+
+    expect(() => cmdTeam(ctx, ['wat'])).toThrow(`exit(${ExitCodes.ERROR})`);
+  });
+
+  it('cmdTeam summary keeps shared-team aggregate view', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({ egp: ['claude'] });
+
+    cmdTeam(ctx, ['ls', '--summary']);
+
+    expect(ctx.ui.table).toHaveBeenCalledWith(['TEAM', 'AGENTS'], [['egp', 'claude']]);
+  });
+
+  it('cmdTeam table groups by team/workspace scope before pane order', () => {
+    const ctx = createCtx(testDir);
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%3',
+        target: 'main:3.0',
+        cwd: '/tmp',
+        command: 'zsh',
+        suggestedName: null,
+        registrations: [],
+      },
+      {
+        pane: '%1',
+        target: 'main:1.0',
+        cwd: '/repo',
+        command: 'claude',
+        suggestedName: 'claude',
+        registrations: [{ scopeType: 'workspace', scope: '/repo', agent: 'claude' }],
+      },
+      {
+        pane: '%2',
+        target: 'main:2.0',
+        cwd: '/repo',
+        command: 'codex',
+        suggestedName: 'codex',
+        registrations: [{ scopeType: 'team', scope: 'beta', agent: 'codex' }],
+      },
+      {
+        pane: '%4',
+        target: 'main:4.0',
+        cwd: '/repo',
+        command: 'gemini',
+        suggestedName: 'gemini',
+        registrations: [{ scopeType: 'team', scope: 'alpha', agent: 'gemini' }],
+      },
+    ]);
+
+    cmdTeam(ctx, ['ls']);
+
+    expect(logSpy.mock.calls.map((call) => call[0])).toEqual([
+      'Team: alpha (gemini)',
+      '',
+      'Team: beta (codex)',
+      '',
+      'Workspace: /repo (claude)',
+      '',
+      'Unregistered panes',
+    ]);
+    expect((ctx.ui.table as ReturnType<typeof vi.fn>).mock.calls.map((call) => call[0])).toEqual([
+      ['PANE', 'TARGET', 'CWD', 'CMD'],
+      ['PANE', 'TARGET', 'CWD', 'CMD'],
+      ['PANE', 'TARGET', 'CWD', 'CMD'],
+      ['PANE', 'TARGET', 'CWD', 'CMD'],
+    ]);
+    expect((ctx.ui.table as ReturnType<typeof vi.fn>).mock.calls[0][1]).toEqual([
+      ['%4', 'main:4.0', '/repo', 'gemini'],
+    ]);
+    logSpy.mockRestore();
+  });
+
+  it('cmdTeam rm supports dry-run and force removal', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
+      egp: ['claude'],
+    });
+    (ctx.tmux.removeTeam as ReturnType<typeof vi.fn>).mockReturnValue({
+      removed: 1,
+      agents: ['claude'],
+    });
+
+    cmdTeam(ctx, ['rm', 'egp', '--dry-run']);
+    expect(ctx.tmux.removeTeam).not.toHaveBeenCalled();
+
+    ctx.flags.force = true;
+    cmdTeam(ctx, ['rm', 'egp']);
+    expect(ctx.tmux.removeTeam).toHaveBeenCalledWith('egp');
+  });
+
+  it('cmdTeam rm requires --force and errors for missing teams', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({ egp: ['claude'] });
+
+    expect(() => cmdTeam(ctx, ['rm', 'egp'])).toThrow(`exit(${ExitCodes.ERROR})`);
+
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({});
+    expect(() => cmdTeam(ctx, ['rm', 'missing', '--force'])).toThrow(
+      `exit(${ExitCodes.PANE_NOT_FOUND})`
+    );
+  });
+
+  it('cmdTeam rm outputs JSON in dry-run and force modes', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({ egp: ['claude'] });
+    (ctx.tmux.removeTeam as ReturnType<typeof vi.fn>).mockReturnValue({
+      removed: 1,
+      agents: ['claude'],
+    });
+
+    cmdTeam(ctx, ['rm', 'egp', '--dry-run']);
+    ctx.flags.force = true;
+    cmdTeam(ctx, ['rm', 'egp']);
+
+    expect((ctx.ui as any).jsonCalls).toEqual([
+      { team: 'egp', dryRun: true, agents: ['claude'], removed: 0 },
+      { team: 'egp', removed: 1, agents: ['claude'] },
+    ]);
+  });
+
   it('cmdCompletion prints scripts', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     cmdCompletion('bash');

package/src/commands/completion.ts

@@ -16,15 +16,15 @@ _tmux-team() {
     'add:Add a new agent'
     'update:Update agent config'
     'remove:Remove an agent'
-    'init:Create empty tmux-team.json'
+    'migrate:Copy legacy tmux-team.json registry into tmux metadata'
+    'team:Manage shared teams'
+    'init:Create empty legacy tmux-team.json'
     'completion:Output shell completion script'
     'help:Show help message'
   )
 
   _get_agents() {
-    if [[ -f ./tmux-team.json ]]; then
-      agents=(\${(f)"$(node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync('./tmux-team.json'))).join('\\\\n'))" 2>/dev/null)"})
-    fi
+    agents=(\${(f)"$(tmux-team list --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{const j=JSON.parse(s); console.log(Object.keys(j.agents||{}).join("\\n"))}catch{}})')"})
   }
 
   if (( CURRENT == 2 )); then
@@ -64,16 +64,14 @@ const bashCompletion = `_tmux_team() {
   cur="\${COMP_WORDS[COMP_CWORD]}"
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
-  commands="talk check list add update remove init completion help"
+  commands="talk check list add update remove migrate team init completion help"
 
   if [[ \${COMP_CWORD} -eq 1 ]]; then
     COMPREPLY=( $(compgen -W "\${commands}" -- \${cur}) )
   elif [[ \${COMP_CWORD} -eq 2 ]]; then
     case "\${prev}" in
       talk|check|update|remove|rm)
-        if [[ -f ./tmux-team.json ]]; then
-          agents=$(node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync('./tmux-team.json'))).join(' '))" 2>/dev/null)
-        fi
+        agents=$(tmux-team list --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{const j=JSON.parse(s); console.log(Object.keys(j.agents||{}).join(" "))}catch{}})')
         if [[ "\${prev}" == "talk" ]]; then
           agents="\${agents} all"
         fi

package/src/commands/config-command.test.ts

@@ -51,6 +51,13 @@ function createCtx(
     capture: vi.fn(),
     listPanes: vi.fn(() => []),
     getCurrentPaneId: vi.fn(() => null),
+    resolvePaneTarget: vi.fn((target: string) => target),
+    getAgentRegistry: vi.fn(() => ({ paneRegistry: {}, agents: {} })),
+    setAgentRegistration: vi.fn(),
+    clearAgentRegistration: vi.fn(() => false),
+    listTeams: vi.fn(() => ({})),
+    listTeamPanes: vi.fn(() => []),
+    removeTeam: vi.fn(() => ({ removed: 0, agents: [] })),
   };
   return {
     argv: [],
@@ -167,10 +174,7 @@ describe('cmdConfig', () => {
 
   it('shows sources in table mode with local settings', () => {
     const ctx = createCtx(testDir);
-    fs.writeFileSync(
-      ctx.paths.localConfig,
-      JSON.stringify({ $config: { mode: 'wait' } })
-    );
+    fs.writeFileSync(ctx.paths.localConfig, JSON.stringify({ $config: { mode: 'wait' } }));
     cmdConfig(ctx, ['show']);
     expect(ctx.ui.table).toHaveBeenCalled();
     // The table call should include (local) source
@@ -181,10 +185,7 @@ describe('cmdConfig', () => {
   it('shows sources in table mode with global settings', () => {
     const ctx = createCtx(testDir);
     fs.mkdirSync(ctx.paths.globalDir, { recursive: true });
-    fs.writeFileSync(
-      ctx.paths.globalConfig,
-      JSON.stringify({ mode: 'wait' })
-    );
+    fs.writeFileSync(ctx.paths.globalConfig, JSON.stringify({ mode: 'wait' }));
     cmdConfig(ctx, ['show']);
     expect(ctx.ui.table).toHaveBeenCalled();
     const tableCall = (ctx.ui.table as ReturnType<typeof vi.fn>).mock.calls[0];

package/src/commands/config.ts

@@ -114,11 +114,7 @@ function showConfig(ctx: Context): void {
       ['mode', ctx.config.mode, modeSource],
       ['preambleMode', ctx.config.preambleMode, preambleSource],
       ['preambleEvery', String(ctx.config.defaults.preambleEvery), preambleEverySource],
-      [
-        'pasteEnterDelayMs',
-        String(ctx.config.defaults.pasteEnterDelayMs),
-        pasteEnterDelaySource,
-      ],
+      ['pasteEnterDelayMs', String(ctx.config.defaults.pasteEnterDelayMs), pasteEnterDelaySource],
       ['defaults.timeout', String(ctx.config.defaults.timeout), '(global)'],
       ['defaults.pollInterval', String(ctx.config.defaults.pollInterval), '(global)'],
       ['defaults.captureLines', String(ctx.config.defaults.captureLines), '(global)'],

package/src/commands/help.ts

@@ -52,6 +52,8 @@ ${colors.yellow('COMMANDS')}
   ${colors.green('this')} <name> [remark]       Register current pane as an agent
   ${colors.green('update')} <name> [options]     Update an agent's config
   ${colors.green('remove')} <name>               Remove an agent
+  ${colors.green('migrate')} [--dry-run]          Copy legacy JSON registry to tmux metadata
+  ${colors.green('team')} [ls|rm]                 Inspect pane scopes and manage teams
   ${colors.green('install')} [claude|codex]       Install tmux-team for an AI agent
   ${colors.green('init')}                        Create empty tmux-team.json
   ${colors.green('config')} [show|set|clear]     View/modify settings
@@ -89,9 +91,10 @@ ${colors.yellow('EXAMPLES')}${
   tmux-team add codex 10.1 "Code review specialist"
 
 ${colors.yellow('CONFIG')}
-  Local:  ./tmux-team.json (pane registry + $config override)
+  Runtime: tmux pane metadata (agent registry)
+  Local:  ./tmux-team.json (legacy registry + $config override)
   Global: ~/.config/tmux-team/config.json (settings)
-  Teams:  ~/.config/tmux-team/teams/<name>.json (shared teams)
+  Teams:  tmux pane metadata; team ls shows pane cwd + workspace/team scopes
 
 ${colors.yellow('CHANGE MODE')}
   tmux-team config set mode wait            ${colors.dim('Enable wait mode (local)')}

package/src/commands/install.test.ts

@@ -26,7 +26,14 @@ function createCtx(testDir: string, overrides?: Partial<{ flags: Partial<Flags>
   const config: ResolvedConfig = {
     mode: 'polling',
     preambleMode: 'always',
-    defaults: { timeout: 180, pollInterval: 1, captureLines: 100, maxCaptureLines: 2000, preambleEvery: 3, pasteEnterDelayMs: 500 },
+    defaults: {
+      timeout: 180,
+      pollInterval: 1,
+      captureLines: 100,
+      maxCaptureLines: 2000,
+      preambleEvery: 3,
+      pasteEnterDelayMs: 500,
+    },
     agents: {},
     paneRegistry: {},
   };
@@ -36,6 +43,13 @@ function createCtx(testDir: string, overrides?: Partial<{ flags: Partial<Flags>
     capture: vi.fn(),
     listPanes: vi.fn(() => []),
     getCurrentPaneId: vi.fn(() => null),
+    resolvePaneTarget: vi.fn((target: string) => target),
+    getAgentRegistry: vi.fn(() => ({ paneRegistry: {}, agents: {} })),
+    setAgentRegistration: vi.fn(),
+    clearAgentRegistration: vi.fn(() => false),
+    listTeams: vi.fn(() => ({})),
+    listTeamPanes: vi.fn(() => []),
+    removeTeam: vi.fn(() => ({ removed: 0, agents: [] })),
   };
   return {
     argv: [],

package/src/commands/list.ts

@@ -15,7 +15,9 @@ export function cmdList(ctx: Context): void {
 
   if (agents.length === 0) {
     if (flags.team) {
-      ui.info(`No agents in team "${flags.team}". Use 'tmt this <name> --team ${flags.team}' to add one.`);
+      ui.info(
+        `No agents in team "${flags.team}". Use 'tmt this <name> --team ${flags.team}' to add one.`
+      );
     } else {
       ui.info("No agents configured. Use 'tmux-team add <name> <pane>' to add one.");
     }
@@ -26,6 +28,10 @@ export function cmdList(ctx: Context): void {
   if (flags.team) {
     console.log(`Team: ${flags.team}`);
     console.log();
+  } else if (config.registrySource === 'legacy') {
+    ui.warn(
+      'Using legacy tmux-team.json registry. Run `tmt migrate` to store registrations in tmux.'
+    );
   }
   ui.table(
     ['NAME', 'PANE', 'REMARK'],

package/src/commands/migrate.ts

@@ -0,0 +1,84 @@
+// ─────────────────────────────────────────────────────────────
+// migrate command - copy legacy JSON registry into tmux metadata
+// ─────────────────────────────────────────────────────────────
+
+import type { Context, PaneEntry } from '../types.js';
+import { ExitCodes } from '../exits.js';
+import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
+import { getRegistryScope, registrationFromEntry, scopeLabel } from '../registry.js';
+
+interface MigrationItem {
+  agent: string;
+  fromPane: string;
+  pane: string;
+  remark?: string;
+  status: 'ready' | 'migrated';
+}
+
+export function cmdMigrate(ctx: Context, args: string[]): void {
+  const dryRun = args.includes('--dry-run');
+  const cleanup = args.includes('--cleanup');
+  const { ui, paths, flags, tmux, exit } = ctx;
+  const localConfig = loadLocalConfigFile(paths);
+  const scope = getRegistryScope(ctx);
+  const items: MigrationItem[] = [];
+
+  for (const [agentName, rawEntry] of Object.entries(localConfig)) {
+    if (agentName === '$config') continue;
+    const entry = rawEntry as PaneEntry | undefined;
+    if (!entry?.pane) continue;
+
+    const pane = tmux.resolvePaneTarget(entry.pane);
+    if (!pane) {
+      ui.error(`Pane '${entry.pane}' for agent '${agentName}' not found. Is tmux running?`);
+      exit(ExitCodes.PANE_NOT_FOUND);
+    }
+    const paneId = pane as string;
+
+    items.push({
+      agent: agentName,
+      fromPane: entry.pane,
+      pane: paneId,
+      ...(entry.remark !== undefined && { remark: entry.remark }),
+      status: dryRun ? 'ready' : 'migrated',
+    });
+
+    if (!dryRun) {
+      tmux.setAgentRegistration(paneId, scope, registrationFromEntry(agentName, entry));
+    }
+  }
+
+  if (!dryRun && cleanup && items.length > 0) {
+    for (const item of items) {
+      delete localConfig[item.agent];
+    }
+    saveLocalConfigFile(paths, localConfig);
+  }
+
+  if (flags.json) {
+    ui.json({
+      dryRun,
+      cleanup,
+      scope,
+      migrated: dryRun ? 0 : items.length,
+      items,
+    });
+    return;
+  }
+
+  if (items.length === 0) {
+    ui.info(`No legacy agents found in ${paths.localConfig}`);
+    return;
+  }
+
+  const action = dryRun ? 'Would migrate' : 'Migrated';
+  ui.success(`${action} ${items.length} agent(s) to ${scopeLabel(scope)}`);
+  ui.table(
+    ['AGENT', 'FROM', 'PANE', 'REMARK'],
+    items.map((item) => [item.agent, item.fromPane, item.pane, item.remark ?? '-'])
+  );
+
+  if (!dryRun && !cleanup) {
+    ui.info('Legacy JSON was left in place. Use --cleanup to remove migrated agent entries.');
+  }
+}